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forms the most comprehensive and advanced solution 
for developing completely portable GUI applications. 


Macintosh ^ 


◄ OPEN LOOK 


WINDOWS NT 
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CHARACTER SYSTEMS 


Applications in a 


Master the art of multi-platform GUIs. 

XVT Software is the leading choice of world-class 
developers for one reason: It is the simplest, quickest path 
to building quality applications that port to every GUI 
without compromises in look-and-feel or performance. 

Plus, it’s easier to learn and use than native toolkits, so your 
time and effort goes into your application, not your GUIs. 

XVT gives you simultaneous original GUIs. 

Because XVT uses native GUI objects, your application 
is indistinguishable from one written directly to the native 
toolkit. Through our layered architecture, you achieve 
equivalent cross-platform functionality appropriate to each 
GUI, without the overhead and inflexibility of proprietary 
emulation-based systems. 


Developers judge XVT to be a masterpiece. 

XVT is the base document for the IEEE’s GUI 
standardization effort. Our thousands of customers include 
internal and commercial developers like: Alcoa, Amoco, 
AT&T, Avis, Ford, General Motors, Grammatik/Reference 
Software, Kodak, Lockheed, NCR, NEC, NIST, Novell, 
Rockwell, Siemens, Sony, Southwestern Bell, Tandem, 
Uniplex, Unisys, US Army and US West. 

Call now for a free XVT Technical Overview 
and Demo. 

Ask about XVT training in FL, NY, WA, TX, NJ, and more. 


XVT puts complete C/C++ solutions at 
your fingertips. 

The XVT Solutions for C and C++ each include an 
Interactive Design Tool and the XVT Portability Toolkit. 

Our Design tools let you use your mouse to design 
and lay out your GUI, using native and custom controls, 
then test it on all your target platforms before generating 
and compiling your code. 

When combined with in-depth consulting, training 
and support, plus a wide range of Partners products, XVT 
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The portable GUI development solution. 
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XVT Software Inc. 4900 Pearl East Cir. Boulder, CO 80301 
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For European inquiries, contact: Precision Software GmbH 
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800 - 755-8649 


Who Do You Call When You Need NT Connections? 

NTDirect. your one source for Windows NT™ to Unix connectivity 

Yes, we know that Windows NT hasn't really shipped yet (at least not when this ad was created) but we want you to 
know that there is a company dedicated to bringing you the best NT products at the best prices. And anyone moving to 
NT needs windows and Unix connectivity products today. As NT goes gold we expect that all the products you see in this 
ad will start shipping an NT version. Development tools such as SliekEdit and SourceSafe are already available. Now 
you know where to get them. Call us today and we'll keep you on our mailing list for the latest tools. We ship everything 
via Federal Express to ensure 011 -time delivery w ithin 2 business days. 3 days to most of Europe. 


SourceSafe 



OWE TREE Software 


Project oriented 
version control 


SourceSafe is the cross-platform project 
oriented version control software that does¬ 
n't try and write your program for you. It 
takes care of your maintenance and tracking 
responsibilities, freeing windows NT 
you up to concentrate on * 9 
programming- Also avail- 
able for Unix. Call. 



"SliekEdit is the only 


editor I use" 


- Dave Cutler, Director of Windows NT Development. 


PC Week added “overall, the easiest editor to learn and 
use.” Full undo and redo (32,767 steps!), procedure tagging, 
on-line manual, run compiler from editor, multiple clipboard 
support, expression search and replace, 
Windows NT d 0Cum ent math, and a typeless REXX-like 
$ M A C macro language. Also for SCO Unix, AIX, HP-UX, 
■ “ ^ SunOS, DOS and Windows. 


AIR! - Super Fast TCP NFS 

EASY TO USE AND SIMPLE TO INSTALL 

You get a super fast TCP/IP w/ NFS. And since it is 
a windows application you can install it in high 
memory, freeing up your valuable low memory for 
other uses. AIR includes TELNET/VT220, FTP, LPR, 
Ping and Sockets. It supports both 
ODI and NDIS drivers and popular PC 
X servers. We've even thrown in AIRMAIL, a Win¬ 
dows implementation of Internet Mail. And you get a 
full year of free support and free software updates. 

Windows available today. Version for NT available when NT ships. 



21 PCs 

*162 ea 



Turn your PC into an 
X Terminal with XVision 


Whether you need to connect one, five, 20,50, 
or over 100 PC's to your Unix system, XVision 
and UniDirect make it easy. Get industry stan¬ 
dard X terminal access 


from your Windows 
System. Ask about 
optional serial connections. Windows available 
today. Coming soon for NT. 


MS-Windows 


5 Pack s 1695 
Evaluation ! 49. NT Soon 


Smooth skating from Windows, 
DOS, Novell or NT to Unix 

For one low price, you can connect all your PCs at one 
location to your Unix system with ICE.TEN.PLUS. Ver¬ 
sions for both MS-DOS and MS-Windows are 
included in the same package. You get great 
Wyse terminal emulation and two-way file trans- 
nnt/uiin fer between DOS and Unix. You also get 

. _ Host Print which allows any DOS PC appli- * — 

* 240 cation to print to any Unix printer on your host system. 



.,. Ask about ICE.TCP for Novell to Unix connectivity. 

Connect to SCO Unix 


GET IT NOW! 



NTDirect is your source for NT and Windows to Unix connectivity 
products. Every product featured in this 
ad is backed by our exclusive 45 day 
100% Money Back Guarantee. Call us and 
ask for our latest list of NT software. We also 
distribute CodeBase, Chameleon, FTP, MKS Toolkit, 

Sun PC-NFS, Unix training videos and more. 

International 


Benelux 32-1061-1919 Singapore 657-484-511 Sweden 31-918-832 U.K. 788-552-005 
Fine Print: VISA, MasterCard, AmericanExpress, COO, Approved PO's. US orders shipped FedEx 
2nd Day. ! 4.50 per order shipping & handling. COD is s 5 (US). International shipping as quoted. 
NTDirect, a UniDirect division, One Venture '150, Irvine, CA 92718.714-453-2999. 

Unix is a trademark of USL Windows NT is a trademark of Microsoft Corporation. All prices and specifications are subject to change without notice. 


FAX: 714-707-3095 ▼ THF#1 NAME IN NT TO UNIX CONNECTIVITY ▼ 714-453-2999 
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Visual Implementation: Checklist Boxes. 6 

In "The Windows Interface, an application design guide," Microsoft describes multiple-selec¬ 
tion listboxes, or checklist boxes. These are listboxes tailored for selecting multiple items by 
supplying a checkbox in each listbox entry. The checkboxes indicate to the user that multiple 
selections are possible and clearly show which entries have been selected. The windows API 
offers no direct support for checklist boxes, but this article provides complete, ready-to-use 
code you can use in your own application. 

Steven Palmer 

Practical C+ + : Introducing WUIMAN. 15 

What better way to explore practical C+ + Windows programming than with a realistic code 
project? This column begins the design and construction of WUIMAN, a Windows User Inter¬ 
face MANager. WUIMAN lets you (or even an end user) create and modify your program’s 
user interface while it is running. This first installment discusses general design goals and 
begins implementing some of the low-level classes in the project. 

Ron Burk 


Features 


Windows NT Remote Procedure Calls . . . . 29 

One of the goals of Windows NT's design is to provide distributed computing, the ability to 
get your work done using resources on more than one machine. The Remote Procedure Call 
(RPC) is the heart of NT’s distributed computing ability. You can use RPC to call code that 
resides on another computer as though it were a local function call, even passing complex 
parameter lists. This article introduces you to RPC concepts and demonstrates RPC on NT 
with a distributed program for locating prime numbers. 

Guy Eddon 

A Range-Definable Custom Edit Control. 55 

Probably the most common kind of custom control you will want to make is some variation of 
an edit control. The best way to do this is often by subclassing the standard edit control. This 
article provides functions to handle the repetitive tasks of subclassing and demonstrates a 
range-restricted edit control. 

William Smith 


Shareware Spotlight 


Threads for Windows . . 50 

One of the promises of Win32 is multi-threading, the ability to create multiple threads of con¬ 
trol within a single application. Threads provide a useful paradigm for implementing tasks 
such as background printing or calculating. Why wait for Win32? Victor looks at a package 
that claims to deliver multi-threading for your Windows 3.1 application today. 

Victor Volkman 

Cover photo by Michel Tcherevkov 
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Product Spotlight 


ZylNDEX Developer’s Toolkit. 43 

ZylNDEX Developer’s Toolkit is a Windows 3.1 product that helps you create and use fast in¬ 
dexes into large amounts of data stored in text files, word processing documents, spread¬ 
sheets, and databases. As storage media such as disk space and CD-ROM continue to drop 
in price, more programmers will need this kind of technology for providing access to massive 
data sites. 

Bruce Graves 


Columns 


Tech Tips. 63 

Leor shows how he uses batch files to automate switching between Borland and Microsoft 
compilers, and Larry Hansen provides a little interactive program for converting fixed-length 
records to variable-length records — a common task when you need to analyze mainframe 
data on the PC. 

Leor Zolman 

Windows Questions and Answers. . 71 

Tony Milosz poetically describes a problem in calling SetDlgItemText() on a control in 
another application, which Paul discovers is a bug in Windows. To help a reader track down 
the cause of a hung system, Paul walks through some of the more obtuse commands in the 
WDEB386 debugger. Finally, Paul points a reader to a VxD for reliably determining whether a 
DOS application is running windowed or full screen, and answers a reader comment on a 
previous column. 

Paul Bonneau 
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GEnle - in the Windows Roundtable at page 1335 (Keyword:Windows). 

USENET (Archived by UUNET Technologies): 
uunet!~/published/windowsdos/19YY/monYY.zip 

Accessible via anonymous FTP from ftp.uu.net or via uucp from (900) GOT-SRCS (login name “uucp,” 
no password, $.50 per minute). 

BBSs: 

Phoenix Chapter ACM Library - (602) 970-0474; The Programmer’s Corner - 301-596-7692 or 
(410) 995-6873; The Courts of Chaos — (501) 985-0059; EmmaSoft Shareware Board — 607-533-7072; 
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Are you 
avoiding 
version 
control? 

Version control isn't just for teams! 

If you’ve ever accidentally deleted 
source crucial to a project, or 
introduced a bug into working code, 
you know you need a version control 
system. Until now VCS’s have been 
expensive and notoriously difficult to 
maintain. Introducing Source Control: 
finally, individual programmers can 
track incremental code changes, just 
like large companies do for their most 
important projects! 

Think of it as object-oriented 
version control. 

Source Control’s "project orientation" 
will take full advantage of your object- 
oriented code by allowing you to share 
code among active projects. 

Developing for multiple platforms? 

Source Control is available now for DOS, 
Windows, NT, Macintosh, OS/2 and 
UNIX. All of these versions are 
transparent across a network so you 
can work with one integrated code base 
rather than memaging time consuming, 
unnecessarily redundant systems. 

If you are part of a team... 

Source Control grows easily to meet the 
needs of team development. A single 
user can get started for less than $300 
(list price) and licenses are available in 
increments of five, ten and more. You 
can economically install Source Control 
on your server and get instant, 
project-wide status reports. Find out 
the who, what, where and when of each 
component as you speed your team to 
that final build deadline. 

Upgrade from PVCS! 

Make a quick transition from your 
current configuration management 
system with Source Control’s PVCS 
conversion utility. Add Powerline’s 
make utility, Source Make, and 
automatically update files without time 
consuming manual check-in/check-out 
procedures. Start on your way to a fully 
integrated configuration management 
system! 

Call for more information! 

Powerline Software is dedicated to 
providing a suite of compiler and 
platform independent developer’s tools, 
including Source Print+, for source code 
management and Source View, the 
run-time debugger for C and C++. 

SOURCE CONTROL 
SOURCE MAKE 


1 - 800 - 257-5773 



1306 Western Avenue, Suite 203, Seattle, WA 98101 
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From 

the Editor 


As a contributing editor, Victor Volkman has long provided us with excellent 
articles about programming tools and technical specifications, as well as general PC 
programming articles. This month, he starts a new bimonthly column covering the 
best of shareware Windows programming products. If you have a favorite shareware 
product that you want to bring to his attention, you can upload it to the HAL 9000 
BBS at (313)663-4173 or (313) 663-3959. Alternately, you can send him email at 
sysop0hal9k.com. The general criteria for products appearing in Shareware Spotlight 
are: 

• The product is for Windows programmers. 

• The product is user-supported, not freeware. 

• Product evaluation copies can be freely shared (e.g., via BBS). 

• The product lets you “try before you buy” (fully functional). 

• Users are able to purchase source code. 

Allen Holub used to write a great column for Dr. Dobb’s Journal in which he 
sometimes took on fun projects, such as writing a replacement shell for com¬ 
mand. com. I always enjoyed his column because it gave me an opportunity to see 
how someone else tackled PC programming problems in a real program. I hope to 
emulate Allen’s example with WUIMAN, a new programming project I’m writing 
about in my “Practical C++” column. WUIMAN is a user interface manager designed to 
provide a simple, visual style of creating and maintaining Windows user interfaces. 
Since I’m writing it as I go, it will be interesting to see if the final product looks 
anything like the initial vision I 

My pet peeve of the month is with C++ compiler vendors. Much of the potential 
for reusable C++ DLLs is stymied by gratuitous incompatibilities. The most obvious 
problem is that Borland and Microsoft use different name-mangling algorithms, so 
you can't even correctly extern a function that was compiled with someone else’s 
compiler. Among the more insidious problems is the fact that Borland and Microsoft 
implement the global new operator differently (one vendor allocates shared memory 
and the other allocates private memory). The many incompatibilities help discourage 
packaging third-party C++ libraries in DLLs, since you either have to include source 
code or else create and maintain a separate DLL for each compiler you want to 
support The compiler vendors don't have a lot of motivation to resolve these in¬ 
compatibilities, since they help tie you to their product. In a better world, the Win¬ 
dows C++ compiler vendors would get together and agree on a common binary 
specification for C++ objects and C++ DLLs and everyone would be a little more 
productive for it. 


Ron Burk 

Editor 

CIS: 70302,2566 ; BIX: rlburk-, Internet: ronb@rdpub.com ("... !uunet!rdpub!ronb") 
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PhaseS Will Make You a Winner in 
Windows Application Development 


Windows is a trademark of Microsoft Corporation. Turbo Pascal for Windows and Borland Pascal 7.0 are trademarks of Borland International, Inc. All 
other trademarks or service marks are recognized as the property of their respective owners. 
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Visual Development 

The Phase3 visual development environment 
provides a comprehensive suite of tools for 
screen creation. All standard Windows 
screen objects - push buttons, radio buttons, 
dialog boxes, etc. - are selectable from icon 
bars and are dynamically placed and sized 
on the screen as appropriate for the 
application. Standard Windows APIs are 
available from list boxes and are supported 
with on-line documentation. 


Phase3 Database 

Phase3 includes a relationally complete 
database supplied as a Windows DLL. The 
database supports complex data relation¬ 
ships and access and data manipulation by 
any language through a comprehensive 
suite of supplied database routines. 
Database integrity is enhanced with 
rollback recovery and transaction control. 
The Phase3 data dictionary simplifies data 
model definition and maintenance. 


Query and Reporting 

The Report Writer includes standard 
features like flexible headers, footers, free 
text, calculated fields, sort group sections 
and breaks, and subtotals. Reports can also 
include bitmaps of drawings and photo¬ 
graphic images. Queries are executed with 
the Database Browser which also allows 
data entry and manipulation. Railway 
diagrams assist in query creation, prompt¬ 
ing the user for appropriate selections and 
eliminating syntactical errors. 


Lower CASE, E-R Modeling 

Phase3 automates logical data model design 
with Entity-Relationship modeling. After a 
user describes entity relationships graphi¬ 
cally and enters field descriptions, Phase3 
generates the physical database based on an 
analysis of the entity relationships. Phase3 
automatically includes foreign keys in 
appropriate tables and restructures the 
database as requirements change. Phase3 
suggests appropriate referential integrity 
constraints to be enforced at runtime. 


Hierarchy Chart 

Phase3 maintains a graphical map of an entire 
application. The Hierarchy Chart includes all 
windows, dialogs, reports, and code routines. 
To access the underlying C or Pascal source 
code, simply point-and-ciick on any node. 
Phase3 generated source is easily accessed 
and extended with user written routines. User 
code is preserved even if an application is 
regenerated. The Hierarchy Chart and E-R 
Diagram provide instant core documentation 
for an application. 


Help Generator 

The Phase3 Help Generator allows the easy 
creation of a complete Windows application 
help subsystem including context sensitive 
on-line help. The Help Generator includes its 
own text editor that gives complete control 
over the content, appearance, and branching 
logic through highlighted trigger text. Phase3 
generates a Windows compatible file with an 
“.HLP" extension that is then accessible 
from within the Phase3 created application. 
No other external tools are required. 


Order Now at $395 

800 - 851-5650 


Or Call for Free Demo Disk 

USA: Fax (805) 641-9083 
Australia: Fax (06) 285-4169 

j-/60 Day Money-Back Guaranteed, 

Order Phase3 at the special introduc¬ 
tory price of $395 [normally $795] 
before August 31. If you’re unhappy 
for any reason return the product in 
marketable condition within 60 days 
l -v for a complete refund. > 


Phase3 is the quickest and 
easiest way to develop a 
winning Windows applica¬ 
tion. Phase3 has everything 
you need to design, develop, 
deliver, and maintain a 
complex application. 


Whether you are developing 
for resale or internal use, Phase3 is your 
best choice. Phase3 applications are roy¬ 
alty free and do not require any run-time 
engine. And Phase3 generates high perfor¬ 
mance applications with ANSI standard C, 
Turbo Pascal for Windows, and Borland 
Pascal. The choice is yours. 






























Steven Palmer is the Chief Software Engineer for LJ Technical Systems Ltd, a British 
firm developing Computer-Aided Training systems for electronics and microelectronics 
students. He may be contacted on CompuServe: 100031,504. 


Visual Implementation: 
Checklist Boxes 


Steven Palmer 


Visual Programming 


Listboxes, as their name implies, show lists of things. Whether the items listed 
are filenames, colors, or a set of items, the boxes all behave in the same fashion: 
they let the user pick one or more items from a list of related items. Under Win¬ 
dows, as in most other graphical user interfaces, as each item is selected, the listbox 
highlights the item and its background in a different color. The Windows API for 
listboxes supports various styles, such as sorted, multicolumn, and so on. 

You have probably seen one style of Windows listbox that is not directly sup¬ 
ported by the Windows API for listboxes, especially if you have used one of 
Microsoft's setup programs. At some point during the setup, you are usually allowed 
to select which portions of the product you want to install. Although the options are 
displayed in standard listbox fashion, they are not highlighted when you select 
them. Instead, a check-box to the right or left is turned on or off as you click the 
item. Figure 1 demonstrates this kind of listbox. 

This variation on the standard listbox is called a multiple selection listbox, a high¬ 
ly confusing name if there ever was one! Normally, you think of multiple selection 
listboxes as listboxes from which you can select more than one item without having 
to hold down the Shift key in between. But Microsoft’s application design guidelines 
either overlook this or prefer a different terminology. Rather than add to the con¬ 
fusion, I will call them "checklist" boxes, which is a more appropriate name consider¬ 
ing their function. Checklist boxes are not part of the Windows interface; they have 
to be especially programmed. This article describes how to implement them in a 
clean, encapsulated manner. 

An Overview of Checklist Boxes 

Checklist boxes typically look like standard listbox items, with the addition of a 
check-box on the right or left of the item text. Microsoft's application design 
guidelines show the check-box on the left, but most applications place it on the 
right. There seems to be no overwhelming advantage for either position, so while 
the code described here places the check-box on the right, you can easily modify it 
to place the check-box on the left. 

When you click any item or press the space-bar, only the check-box changes 
state. If the check-box was unchecked, it is checked, otherwise it remains uncheck¬ 
ed. Neither the color of the item nor the color of its 
background changes. Apart from this, the only other 
visual indication is the obligatory focus rectangle 
around the current item. 


Borland C++ v3.1 
Microsoft C/C++ v7.0a 
Zortech C++ v3.l 
Visual C++ vl.O 
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Introducing ProtoGen+. Visual tools with the most awesome 
workbench ever created for Windows development. 


Discover the ease and 
productivity of visual 
development! 


Visually 

develop 

screens 


he future has arrived—a complete 
point-and-click, WYSIWYG 
workbench that lets you create 
dazzling applications without 
writing a line of code. 

Paint your 
screens. Design 
a menu and link 
screens togeth¬ 
er. Test the flow 
in a live environ¬ 
ment, and gen¬ 
erate code for 
ANSI C, C++ 
for OWL or MFC 
or Pascal with 
objects. It’s that 
easy. 

And this 

open! ProtoGen+ 
will work with 

_ your database, 

compiler, 

libraries and extensions. Powerful 
add-on features, like SQLView offer 


Create a menu 
and canned 
screens & dialogs 


Test the applica¬ 
tion's screen flow in 
a live environment 


Instantly generate 
source code in 
Pascal, C or C++ 


M&EH] 


workbench access to multiple 
databases to develop client/server and 
xBase applications. Snap-in compo¬ 
nents make ProtoGen+ open to future 
development technologies—whatever 
they may be. 

ProtoGen+ is easy to learn, 
speeds your development cycle and 
protects your investment by generat¬ 
ing C,C++ and Pascal. We guarantee 
you'll 
prototype 
and generate 
exciting 
applications 
faster than 


The most powerful, open set of 
Visual Development Tools ever! 




[Mlj 

j STATIC 
j TEXT 

♦ 



HP 

Ieoit T| 

1 TEXT J.| 

[xj 




3 

P 

(Tape! 
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nd-click 

to paint 



screens with bitmaps, 
icons, tables, data valida¬ 
tion, custom colors, fonts, 
3D effects, visual tool¬ 
bars, status lines, balloon 
help, MDI and more! 


you ever 

thought 

possible! 


% 


Bring your applications to life using the latest 
visual design tools! 


P^VfEW 

The Visual Development Edge™ 

All products named are trademarks of their 
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Listing 1 checklst.c — A checklist box control for Windows 

finclude <windows.h> 

hwndList * CreateWindow( "listbox", NULL, 

finclude "checklst.h" 

dwStyle, 0, 0, 0, 0, hwnd, NULL, 

LRESULT export CALLBACK CheckLstWndFn( HWND, UINT, 

lpCreateStruct->hInstance, NULL ); 

SetWindowWord( hwnd, 0, (WORD)hwndList ); 

WPARAM, LPARAM ); 

break; 

static void DoDrawItem( HWND, const DRAWITEMSTRUCT FAR * ); 

} 

BOOL FAR PASCAL RegisterCheckLstClass( HANDLE hlnst ) 

{ 

WNDCLASS wc; 

case WM DRAWITEM: { 

const DRAWITEMSTRUCT FAR * lpDrawItem; 

lpDrawItem - (const DRAWITEMSTRUCT FAR *) IParam; 

wc.hCursor - LoadCursor( NULL, IDC ARROW ); 

DoDrawItem( hwnd, lpDrawItem ); 
return( TRUE ) ; 

wc.hlcon - NULL; 

} 

wc.lpszMenuName ■ NULL; 
wc.lpszClassName- "checklst"; 

case W MEASUREITEM: { 

wc.hbrBackground- (HBRUSH)( COLOR WINDOW + 1 ); 

MEASUREITEMSTRUCT FAR * 1pMeasureltem; 

wc.hlnstance - hlnst; 

TEXTMETRIC tm; 

wc.style - CS HREDRAW | CS VREDRAW; 

HOC hdc; 

wc.lpfnWndProc - CheckLstWndFn; 
wc.cbClsExtra - 0; 

1pMeasureltem - (MEASUREITEMSTRUCT FAR *) IParam; 

wc.cbWndExtra - sizeof( HWND ) + sizeof( LONG ); 

hdc - GetDC( hwnd ); 

if ( JRegisterClass( &wc ) ) 

GetTextMetrics( hdc, &tm ); 

return ( FALSE ); 

lpMeasureItem->itemHeight = 

return ( TRUE ); 

tm.tmHeight + tm.tmExtemal Leading; 

} 

ReleaseDC( hwnd, hdc ); 

LRESULT export CALLBACK CheckLstWndFn(HWND hwnd, 

return ( TRUE ); 

} 

UINT message, WPARAM wParam, LPARAM IParam ) 

{ 

case VW DELETEITEM: 

HWND hwndLlst; 

case VW COMPAREITEM: 

switch( message ) 

/ 

return( SendMessage( GetParent( hwnd ), 
message, wParam, IParam ) ); 

l 

case LB ADDSTRING: 

case WM PARENTNOTIFY: 

case LB INSERTSTRING: 

if( wParam « WM LBUTTONDOWN 

case LB DELETESTRING: 

|| wParam -- WM RBUTTONDOWN 

case LB RESETCONTENT: 

j j wParam « WM MBUTTONDOWN 

case LB SETSEL: 

) 

case LB SETCURSEL: 

{ 

case LB GETSEL: 

return( SendMessage( GetParent( hwnd ), 

case LB GETCURSEL: 

message, wParam, 

case LB GETTEXT: 

MAKELPARAM( hwnd, HIW0RD( IParam ) ) ) ); 

case LB GETTEXTLEN: 

} 

case LB GETCOUNT: 

break; 

case LB_SELECTSTRING: 
case LB DIR: 

case W COMMAND: 

case LB GETTOPINDEX: 

return( SendMessage( GetParent( hwnd ), message. 

case LB FINDSTRING: 

GetDlgCtrlID( hwnd ), 

case LB GETSELCOUNT: 

MAKELPARAM( hwnd, HIW0RD( IParam ) ) ) ); 

case LB GETSELITEMS: 
case LB~SETTABSTOPS: 

case WM SETFOCUS: 

case LB GETHORIZONTALEXTENT: 

hwndList - (HWND)GetWindowWord( hwnd, 0 ); 

case LB SETHORIZONTALEXTENT: 

SetFocus( hwndList ); 

case LB SETCOLUMNWIDTH: 

break; 

case LB SETTOPINDEX: 
case LB GETITEMRECT: 

case WM DESTROY: 

case LB GETITEMDATA: 

hwndList = (HWND)GetWindowWord( hwnd, 0 ); 

case LB SETITEMDATA: 

DestroyWindow( hwndList ); 

case LB SELITEMRANGE: 

break; 

case LB SETCARETINDEX: 
case LB GETCARETINDEX: 

case WM SIZE: { 

case WM ENABLE: 

MEASUREITEMSTRUCT ms; 

case WM ERASEBKGND: 

RECT rc; 

case WM SETREDRAW: 
case WM VSCROLL: 

hwndList * (HWND)GetWindowWord( hwnd, 0 ); 

case WM HSCROLL: 

SendMessagej hwnd, WM MEASUREITEM, 

hwndList * (HWND)GetWindowWord( hwnd, 0 ); 

GetDlgCtrlID( hwnd ), 

return( SendMessage( hwndList, message. 

(LPARAM)(LPSTR)&ms ); 

wParam, IParam ) ); 

GetClientRect( hwnd, &rc ); 

case WM NCCREATE: { 

if( rc.bottom % ms.itemHeight ) 

{ 

LPCREATESTRUCT lpCreateStruct; 

RECT rcWnd; 

DWORD dwStyle; 

lpCreateStruct - (LPCREATESTRUCT)IParam; 

GetWindowRect( hwnd, &rcWnd ); 

SetWindowPos( hwnd, NULL, 0, 0, 

dwStyle * lpCreateStruct->style; 

rcWnd.right - rcWnd.left, 

SetWindowLong( hwnd, 2, (LPARAM)dwStyle ); 

( ( rc.bottom / ms.itemHeight ) * 

dwStyle &- ~WS VSCROLL; 

ms.itemHeight ) + ( ( rcWnd.bottom - 

dwStyle &= ~WS HSCROLL; 

rcWnd.top ) - rc.bottom ), 

SetWindowLong( hwnd, GWL STYLE, (LPARAM)dwStyle ); 

SWP NOACTIVATE | 

break; 

SWP NOMOVE | SWP NOZORDER ); 

) 

GetClientRect( hwnd, &rc ); 

) 

SetWindowPos( hwndList, NULL, 0, 0, 

case WM CREATE: { 

DWORD dwStyle; 

rc.right + GetSystemMetrics( SM CXBORDER ) * 2, 

LPCREATESTRUCT lpCreateStruct; 

rc.bottom + GetSystemMetrics( SM CYBORDER ) *2, 

lpCreateStruct - (LPCREATESTRUCT)IParam; 

SWP_NOACTIVATE | SWP_N0M0VE | SWP_N0Z0RDER ); 
break; 

dwStyle ■ GetWindowLong( hwnd, 2 ) | WS CHILD | 

} 

LBS NOTIFY | LBS OWNERDRAWFIXED j 

} 

LBSHASSTRINGS | LBSMULTIPLESEL; 

return( DefWindowProc( hwnd, message, wParam, IParam )); 
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The Implementation 

Because 90 percent of the checklist box’s behavior is iden¬ 
tical to that of a standard listbox, there is little point in im¬ 
plementing it from scratch. The only difference is in how each 
item is displayed —the behavior of the scroll bars or the focus 
is unchanged. Therefore, the logical place to start is with a 
visual variation of the standard listbox. Windows lets you 
achieve this quite easily through the use of owner-draw 
listboxes. 

Owner-draw listboxes are standard listboxes with one ex¬ 
ception: the appearance of the items in the listbox is defined 
by the program that created them. When Windows needs to 
draw each listbox item, it sends a MM_DRAWITEM message to 
the owner of the listbox, telling it to take whatever action is 
necessary to render the item on the screen. The message in¬ 
cludes information that specifies whether the item is selected 
and whether it has the input focus. Thus, owner-draw 
listboxes let you present items in a more attractive and infor¬ 
mative manner. 

Although owner-draw listboxes seem ideal for implement¬ 
ing checklist boxes, this approach has one major drawback: for 


Listing 1 continued 


) 


static void DoDrawItem( HWND hwnd, 

const DRAWITEMSTRUCT FAR * lpDrawItem ) 


HBRUSH hbr; 
RECT rc; 


re - lpDrawItem->rcItem; 

hbr * CreateSolidBrush( GetSysColor( C0L0R_WIND0W ) ); 
FillRect( lpDrawItem->hDC, &rc, hbr ); 
if( lpDrawItem->itemID 1- (UINT)-l ) { 
char sz[ 200 ]; 

HWND hwndList; 

C0L0RREF crText, crBack; 

RECT rcCheck; 

hwndList = (HWND)GetWindowWord( hwnd, 0 ); 

SendMessage( hwndList, LB_GETTEXT, lpDrawItem->itemID, 
(LONG)(LPSTR)sz ); 

rc.left +« 2; 

crText - SetTextColor( lpDrawItem->hDC, 

GetSysColor( C0L0R_WIND0WTEXT ) ); 
crBack * SetBkColor( lpDrawItem->hDC, 

GetSysColor( C0L0R_WIND0W ) ); 

DrawText( lpDrawItem->hDC, sz, -1, 

&rc, DTNOPREFIX|DT_SINGLELINE|DTVCENTER ); 
SetTextColor( lpDrawItem->hDC, crText ); 

SetBkColor( lpDrawItem->hDC, crBack ); 

SetRect( &rcCheck, ( rc.right - 18 ), rc.top + 1, 

rc.right - 5, rc.bottom - 1 ); 
FrameRect( 1pDrawItem->hDC, &rcCheck, 

GetStockObject( BLACKJRUSH ) ); 


} 


if( lpDrawItem->itemState & 0DS_SELECTED ) { 

MoveTo( lpDrawItem->hDC, rcCheck.left, 
rcCheck.top ); 

LineTo( lpDrawItem->hDC, rcCheck.right, 
rcCheck.bottom ); 

MoveTo( lpDrawItem->hDC, rcCheck.right - 1, 
rcCheck.top ); 

LineTo( lpDrawItem->hDC, rcCheck.left - 1, 
rcCheck.bottom ); 

} 

else { 

InflateRect( &rcCheck, -1, -1 ); 

FillRect( lpDrawItem->hDC, &rcCheck, hbr ); 

} 

DeleteObject( hbr ); 

} 

if( lpDrawItem->itemState & 0DS_F0CUS ) 

DrawFocusRect( lpDrawItem->hDC, 

(LPRECT)&lpDrawItem->rcItem ); 


/* End of File */ 


every dialog procedure that uses checklist boxes, the code to 
draw each checklist box must be included as part of the pro¬ 
cedure’s response to the WM_DRAWITEM message. Although you 
could place this code in a single function and then call it from 
each dialog box procedure that uses checklist boxes, the end 
result is not as neat as it would be if the checklist box were a 
standard Windows control. 

Ideally, you could create an owner-draw listbox in such a 
way that it could be used as an ordinary control. This means 
it would have to somehow intercept and handle the 
UM_DRAWITEM messages that windows implicitly sends to the 
listbox’s parent window (the dialog). Tricky? Yes, but not all 
that complicated. The solution is an approach that you can 
use not just with checklist boxes, but with any other variation 
of a standard Windows control, i call this a “container control." 


Container Controls 


A container control is simply one control that "contains" 
another. In this case, it is a control that contains an ordinary 


Listing 2 checklst.h — Header file for checklst.c 



Multiple Selection List Box Prototypes 
**************************************************y 
BOOL FAR PASCAL RegisterCheckLstClass( HANDLE ); 

/* End of File */ 
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Figure 1 Demonstrating the checklist box control 
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the container control I constructed, and checklst.h (Listing 2) 
contains the declaration for the single function an application 
needs to call in order to use dialog boxes that contain a 
checklist box control. 

The container control itself has no visual aspects: it is 
merely an invisible window, a frame around the listbox that it 
contains. The actual appearance of the container does not 
matter here, just the fact that it can be created as a special 
window class. This encapsulates all the code to handle the 
checklist box in one place, and restricts the interface with the 
user’s application merely to the need to create a window with 
the class name of the checklist box. My implementation 
creates a new window class called "checklst,” for the con¬ 
tainer. All windows subsequently created with this class will 
create the container window, which, in turn, will create the 
nested control. 

The mechanics of window creation pose some problems 
with this approach. The first message Windows sends to the 
checklist box window procedure is a m_NCCREATE message. 
Note that Windows has not completely created the checklist 
box window until after WM_NCCREATE returns. The checklist 
box window procedure needs that window handle to use as 
the parent window when creating the standard listbox control 
that it contains. Therefore, instead of creating the child listbox 
control at m_NCCREATE time, the checklist box window proce¬ 
dure waits for a WM_CREATE message. 

The checklist box window procedure also has to specially 
handle the style bits that arrive with both the WM_NCCREATE 
and M_CREATE messages. It must modify the style bits that 
arrive with the UM_NCCREATE message because these are in¬ 
tended for the listbox that it subsequently creates. The proce¬ 
dure therefore obtains the style bits when it receives the 
m_NCCREATE message and saves a copy in the window extra 
words (arbitrary storage specified when defining the window 
class). Later, when it comes to the m_CREATE message, the 
checklist box control extracts these styles and passes them to 
CreateUindow() to create the actual listbox. 

Why do this in UM_NCCREATE1 Why not wait until the 
UM_CREATE message and avoid having to save the styles? The 
answer is that because the container window must modify its 
own styles so that they are consistent with the styles for the 
checklist box as a whole, but do not conflict with the styles 
for the listbox. As an example, the user can specify the 
WS_VSCROLL style when the checklist box is created. The scroll 
bar is really part of the listbox and not the container class, so 
the container procedure strips off this bit from its own style. If 
it did not, then two scroll bars would be created, one for the 
container window and another for the listbox! 

Once the m_CREATE message has completed, the user has 
two new windows: an invisible container window and the 
listbox that it contains. When the window is drawn on the 
screen, only the listbox appears. 

The checklist box window procedure also has to forward 
messages to the child listbox. For example, when a program¬ 
mer calls SendDlgItemMessage() with the ID of the checklist 
box window to add an item to the listbox, the checklist box 
window procedure must forward the message, otherwise the 
item won't get added to the listbox. The solution here is for 
the container window to capture all these messages the 
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listbox needs to know about, then pass them on. If you look 
at the listing for checklst.c (Listing 1), you will see a whole 
series of messages — from LB_ADDSTRING to WM_HSCROLL — 
which are captured and sent on to the listbox window. The 
return value from the listbox procedure is then passed back 
to the caller. In this way, the container simply acts as a two- 
way tunnel between the application and the listbox. 

The original motivation for this container window was the 
desire to intercept the owner-draw notification messages that 
the listbox sends to its parents. The listbox also sends other 
notification messages that the checklist box control does not 
want to intercept, so the container window traps these mes¬ 
sages, replaces the ID and window handle of the listbox with 
its own, then passes them up to its parent window, which 
should be the user’s application dialog 
procedure. If the application responds 
to these messages, the return value is 
passed back down to the listbox. 

The next piece of tricky code is the 
WM_SIZE message. Remember that 
listboxes are usually drawn to an in¬ 
tegral height so that the last item is not 
truncated vertically. Because the con¬ 
tainer control is responsible for ensuring 
the size of the listbox, it has to com¬ 
pute the listbox size itself. The code ob¬ 
tains the height of each listbox item 
and uses that to size, first the container, 
then the listbox within it. Because the 
container window is a parent of the 
listbox, it has to size itself to fit over 
the listbox; otherwise, the listbox will 
be truncated. 

Finally, the container contains the 
code that handles the owner-draw 
messages emanating from the listbox. 

When it receives a WM_DRAWITEM mes¬ 
sage, it takes over the job of drawing 
the listbox string and the check mark in 
the appropriate state. 

Testing 

Code included on this issue's code 
disk demonstrates how easy it is to im¬ 
plement checklist boxes. The test pro¬ 
gram (see Figure 1) simply draws a 
dialog containing a checklist box, fills it 
with a list of items, then waits for the 
user to click OK. On receipt of the OK 
button, it scans the list looking for 
items that have been marked as 
selected. Other than an initial call to the 
RegisterCheckLstClass() function, it 
contains no other special code. When 
creating the dialog box, I specified a 
control class of "checklst" to create the 
checklist box control. (See the table of 
contents for information on code 
availability.) 


Conclusion 

In this article, I have attempted not only to demonstrate how 
to implement checklist boxes, but also to cast some light on a 
useful technique for enhancing standard windows controls 
without having to re-implement the control from scratch. Al¬ 
though the checklist box could probably be as easily imple¬ 
mented by scattering your code with owner-draw messages, you 
will find the use of a separate window class more convenient 
and easier to integrate with both new and existing applications. 

References 

Microsoft Corporation. The Windows Interface: An Applica¬ 
tion Design Guide. Redmond, WA: Microsoft Press, 1992. ISBN 
1-55615-384-8. □ 


Windows Help Magician 

PC Magazine says "Designing help systems 
with the Help Magician is so easy... 




... that you might even want to 
use it as a hypertext authoring 
tool, independent of providing 
help for a product. Certainly for 
Windows programmers it’s 
indispensable."! - July 1993 
Toolkits section 

Windows Magazine gave the 
Help Magician an "A" for 
creating help files interactively. 


Create, edit, and test help quickly 
in an integrated environment! 


Some original features 

□ Built-in full-featured editor 

□ Create jumps and popups 

□ Create multiple hot spots 

□ Include bitmaps 

□ Create bulleted or numbered lists 

□ Create browse sequences 

□ Use various font styles and colors 

□ Test help files instantly 

□ Quickly writes RTF files 

□ Imports MS Word’s RTF files 

□ Extensive error & syntax checking 

□ Works with any Windows language 
including Visual BASIC and C 


Some version 2.0 features 

□ No memory limitations 

□ Secondary windows 

□ Non-scrolling regions 

□ Set background colors 

□ Advanced paragraph 
formatting 

□ Full macro support 

□ Jump to other help files 

□ Multiple file support 

□ Help window sizing and 
positioning 

□ Built-in spell checker 

□ Writes #define files 


Our competitors require Microsoft Word and use a series of macros, a 
slow process. The Help Magician is a fast, full-blown Windows 
application. One major competitor charges $ 150/yr for tech support; we 
don’t. Simply put, the Help Magician is the best help authoring tool 
money can buy! SITE and Network licensing available. 

SOFTWA1E 
INTEiPHASE 



Order Right Now! 
Just $199! 

800 - 542-2742 


INCORPORATED 


82 Cucumber Hill Rd 
Suite 213 
Foster, Rl 02825 
Voice: (401) 397-2340 
Fax: (401)397-6814 


□ Request 319 on Reader Service Card □ 


Windows/DOS Developer’s Journal — Page 11 


September 1993 





























Gary Slattery Software Developer, Computer Associates 


Now runs Windows 3.1 apps 
for increased productivity. 

“I develop software applications for a living 
and I think OS/2® is a great way to do 
business.” A 32-bit, virtual memory operat¬ 
ing system, OS/2 is the ideal platform for 
developing your DOS, OS/2, Windows® and 
even host-based applications. 

With OS/2 you can boost the power of 
your favorite DOS and Windows tools, 

IBM and OS/2 are registered trademarks and Workplace Shell, CommonView, C Set/2, 
“Operate at a higher level" and OS/2 Crash Protection are trademarks of International 
Business Machines Corporation. All other products are trademarks or registered 
trademarks of their respective companies. ©1993 IBM Corp. 


more 


plus take advantage of over 250 available 
OS/2 development tools and utilities. 


Improved multimedia, CD-ROM, 
PCMCIA and pen support. 



“I use CA Realizer to prototype new 
graphical interfaces. I write code using 
CA C++ and CommonView™ 

(integrated with IBM’s C Set/2 T 
compiler) while I compile 
in the background. And 
when designing reports 
or planning schedules, 

I use CA-RET.” 

OS/2’s pre-emptive multithreaded 
multitasking dynamically manages 

CPU time so you can run DOS, 
Windows and OS/2 apps con¬ 
currently in different sessions with 
maximum efficiency. That means 
you can edit in one window, 
compile in another, link in a third and test in 
a fourth. With OS/2 Crash Protection,™ if one 
application goes down due to a bug, the rest 
you’re working on won’t. “There’s no limit 
to what you can do with this system.... It’s 
definitely made me more productive.” 



Realizer 


The Development Platform of Choice. 

• Enhanced development platform for DOS, Windows and 
OS/2 apps. 

• OS/2 Crash Protection for superior reliability. 

• Pre-emptive multitasking for increased productivity. 

• Virtual memory provides up to 512MB per session. 

• Flat memory model eliminates wrestling with segments. 

• Multiple virtual DOS machines for concurrent app 
testing. 

• Object-oriented Workplace Shell is easy and intuitive. 




Introducing Version 2.1 



arrested 



The object-oriented 
user interface—the Workplace 
Shell™ (WPS)—gives you easy control with 
direct manipulation of visual objects on 
your computer screen. And should you need 
assistance with anything, IBM’s Worldwide 
Developer Assistance Program is always there 
to help. 

Now available on CD-ROM. 



THE SCOOP 
tss .On PrtwttMw miSttm 


[m Vtow UMIttH Fgm* Edit 


aaaj a 


laacjqja adjaa ag* 


Co Norn. 








. ... in 

l as 

1 — iH? 



With 0S/2’s 32-bit architecture, you can 
push your 386 and 486 hardware to the limit, 
and develop spectacular enterprise- 1992 
wide client-server and multimedia 
applications. In fact, OS/2 2.1 has 
superior multimedia support for 
CD-ROM, PCMCIA and pen 
technologies. Here’s your chance 
to develop truly revolutionary 
32-bit applications. With OS/2, now 
there’s nothing stopping you. 

To learn more, call 1 407 982-6408 
now, and get a free white paper on why OS/2 
is the ideal platform for your 
development efforts. 

Operate at a higher level.™ 


PC Magazine Award 
for Technical Excellence 



< ^SSSI\»b a d n s d 

OS/2, Version 2.0 
IBM Corporation 


Use OS/2 to increase productivity of DOS, Windows and 
OS/2 application development. 










































IMPROVE YOUR 

SOFTWARE ENGINEERING WITH 
OBJECT-ORIENTED METHODS 














■ Practical C++ 


15 



Ron Burk 


Visual Programming 


Introducing WUIMAN 


AWK is a little language for manipulating streams of record-oriented text. When it 
first arrived on the UNIX scene, not everyone saw the point. After all, UNIX already 
had ed, vi, grep, fgrep, egrep, sed, and other tools for text manipulation. The authors 
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not handled well by the other tools. The success of AWK in years to come showed 
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eliminated the use of the other UNIX text manipulation tools. 
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an approach to building Windows user interfaces that is visual, interactive, and 
slightly different than most of the tools in the Windows marketplace. 

What Is the Goal? 

This project has been on my back burner for quite a long time, and incorporates 
several different ideas about user interface programming. When I first started read¬ 
ing about Windows 2.0 programming, 1 puzzled over “resources" and wondered at 
the wisdom of all this separate framework for compiling descriptions of the user 
interface. 1 was converted, however, by an article that described “user interface 
management systems” and how they were an important advance in software. The 
article argued that these systems would help separate the user interface from the 

program. Separate user interfaces described with 
standard languages would lead to software that could 
be internationalized without touching the source code, 
and even customized by end users using tools 
designed to operate on the standard structure of the 
user interface description. 
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This sounded like a great idea to me 
at the time, but the promise of user in¬ 
terface management systems seems 
largely unfulfilled among Windows 
programs. Yes, an end user could tech¬ 
nically customize some aspects of a 
Windows program using a tool like 
Borland’s Resource Workshop, but that 
rarely happens in practice. First, end 
users require a great deal more user 
friendliness than programming tools 
offer; the last time I tried to walk an 
end user through Resource Workshop, I 
got a lot of blank stares. Second, the 
user interface information (the . res file) 
is bound into the program’s executable. 
Many people work in a networked en¬ 
vironment, where, for example, 
everyone loads their word processor 
from a single copy on the network, so 
any customization done by one user 
would affect all the other users. Third, 
the user interface description that 
resides in Windows resources is very 
low-level — roughly the same level as 
the Windows API. For example, l wish 
WinWord would remember the last 
eight files I have most recently opened, 
rather than just the last four. Unfor¬ 


tunately, that behavior is totally defined 
by the program code (not the resource 
definitions), so I cannot alter that be¬ 
havior, even though it is clearly part of 
the user interface. 

Visual Basic provided another 
perspective on the problem. I very 
much appreciated the fact that it ex¬ 
posed the user interface in a visual, in¬ 
teractive way. Unfortunately, that is 
true only for the programmer, not the 
end user. Programmers understand im¬ 
plicitly that while it is reasonable to be 
able to move a window around the 
screen and change it to any rectangular 
size, it is not reasonable to expea that 
you can, say, change the "Help” menu 
item of your favorite word processor to 
"Info” just by hitting a key and pointing 
at it. End users are less likely to believe 
that this is an unreasonable request. I 
wanted a user interface manager that 
offered the same power to end users as 
to developers. 

Another problem with Visual Basic is 
that it insists on being the main pro¬ 
gram. If you want to write in C++, you 
have to relegate your code to DLLs that 
provide a non-objea-oriented interface. 


I wanted a user interface manager that 
funaioned as a library, not that forced 
my application code to be in the form 
of a library. Most Windows program¬ 
mers have a lot of existing code and 
are more likely to be interested in a 
new user interface solution if they can 
adopt it incrementally, rather than 
having to convert completely to it 
before seeing any benefits. 

Here are some of the goals I have in 
mind as I start this project. 

• Eliminate, not just reduce, the dis¬ 
tinction between prototyping the 
user interface and running the pro¬ 
gram. 

• Implicitly encourage a separation be¬ 
tween user interface code and pro¬ 
gram code and implicitly encourage 
the developer to expose a cus¬ 
tomizable user interface. 

• Provide, or at least provide a good 
framework for providing, higher-level 
user interface abstractions than the 
windows 3.x API offers. 

• Allow individual end users to cus¬ 
tomize their user interface without 
interfering with any other users of 
the same application. 

• Allow programmers to use the tool 
on as much or as little of their user 
interface as they like. 

• Ignore efficiency in favor of 
modularity and ease of implementa¬ 
tion — 1 want to get something run¬ 
ning quickly, and be able to easily 
change aspects of the package after 
I get experience using it. 

The theme of this column is exploring 
realistic C++ code and problems, and 
this projea has a lot in common with 
most real-life projects: 

• Unrealistic deadlines. I had about 
two weeks to get a crude prototype 
going to convince myself the project 
is basically doable. 

• Lack of resources. The programming 
team consists of the spare time of 
one programmer: mel 

• Lack of experience. I have never 
written a user interface manage¬ 
ment system before, and I’m still 
learning about such systems that 
others have written. 

One thing that is not representative 
about this projea is the amount of peer 
review it will receive. In the vast 
majority of programming shops, the 
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tasks are divvied up and programmers 
scurry off to their cubicles to write code 
that no one else will see until it is too 
large to easily comprehend or change. 
In this project, however, I will get free 
design and code reviews from a good 
number of programmers all along the 
way. 

Although I knew little about other 
user interface management systems 
when I started this product, I've started 
educating myself. In particular, XView 
(one of several user interface toolkits 
available for the X Window System) 
probably has the most in common with 
what I hope to accomplish with this 
project. Visual Basic is also a source of 
ideas and I even seriously considered 
using Visual Basic custom controls 
(VBXs) as a building block, but then 
decided it was just too huge and com¬ 
plicated a specification, it should still be 
possible later to add the ability to use 
VBXs to to this project, treating them as 
add-ons while keeping the framework 
of this software simple. 

While I was a programmer in col¬ 
lege, I wrote a large number of small 
utility programs for users and program¬ 
mers and I used to joke that the most 
important part of program design was 
selecting the program's name — if you 
could select the most perfectly ap¬ 
propriate name for the program's task, 
all other design decisions would flow 
harmoniously from that one. The name 
for this project is WUIMAN (pronounced 
“wooey-man”), which ostensibly stands 
for “Windows User Interface MANager.” 
That is a generic “windows,” by the 
way, not anything trademarked by 
Microsoft I have to admit that half the 
fun of naming programs is getting to 
see grownups try to pronounce non¬ 
sense words! 

What IS WUIMAN? 

How can you place your user inter¬ 
face under the control of software that 
is totally separate from your applica¬ 
tion? My first vague idea was that I 
wanted my WUIMAN Windows 
programs to look something like this: 

int WinMain(/*...*/) 

{ 

WUIMANInit(); 

WUIMAN_Register(Funcl, "Fund"); 

WUIMAN_Register(Func2, "Func2"); 


/*...*/ 

WUIMAN_Register(Funcn, "Funcn"); 

WUIMAN_Run(); 

return 0; 

} 

In other words, my program passes the 
names and addresses of functions that 
may be called as a result of user inter¬ 
face events to the user interface 
manager, and then simply turns control 
over to the user interface manager. This 
is perhaps a little simplistic for complex 
Windows programs, but it seemed like 
a good starting model. 

The first time such a program is run 
(by a developer presumably, not an end 
user), there would be no user interface; 
WUIMAN would pop up its built-in 
design window that would let you start 
creating things such as windows and 
menus. Just as in Visual Basic, items 
such as buttons and menu items could 
generate events, and the user interface 
manager would let you connect these 
events to any of the functions that the 
application had registered. 

The second time you ran this pro¬ 
gram, assuming you had created a main 
window during the first session, that 
main window would appear and 
operate however you designed it. If you 
were smart, you would have also 
defined a menu item or an accelerator 
key that invoked the user interface 
manager, so that you could invoke 
WUIMAN at any time to perform more 
customization. To add more 
functionality, you would still have to 
edit, compile, link, and run, but none of 
that would be required just to create, 
change, or delete elements of the user 
interface - WUIMAN would let you do 
that interactively any time the program 
was running. 

According to the description I've just 
given, a program starts out with no 
user interface; the interface is created 
interactively while the program is run¬ 
ning. That means WUIMAN must have 
some place to store its description of 
the user interface, the sort of informa¬ 
tion that resides in the resource portion 
of a normal Windows program. Figure 1 
shows the big picture. The application 
registers its event-handling functions 
with WUIMAN. The application may also 
supply custom WUIMAN classes to imple¬ 
ment user interface objects (conceptually 
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Figure 1 Windows user interface manager overview 


User 



similar to Visual Basic custom controls). The user can interact 
with WUIMAN to create WUIMAN objects (windows, menus, 
etc.) and to examine and set properties of these objects (con¬ 
ceptually similar to the Visual Basic forms editor). WUIMAN 
maintains these changes in its database. 

As Figure 1 shows, WUIMAN's main purpose is to act as a 
framework for exposing a customizable user interface to the 
user. I plan to build WUIMAN classes that provide specific user 
interface features, but these will just be plugged into the 
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framework —you will be able to easily 
throw them out and replace them with 
your own code. The fact that WUIMAN 
is principally a framework helps make 
the project manageable, since it leaves 
much of the work to the application. 
WUIMAN may not have specific user in¬ 
terface features your application needs 
(such as buttons with graphic faces), but 
it will give you a framework for provid¬ 
ing those features (you could write a 
WUIMAN class that let the user create a 
button and select from a set of graphi¬ 
cal button faces) in a way that allows a 
user interface designer or even an end 
user a lot of control. 

WUIMAN's framework should be 
flexible enough to allow for a variety of 
experiments with user interfaces. One 
thing I am interested in eventually 
tinkering with is constraint-based systems that let you specify 
object behavior in terms of equations. For example, rather 
than specifying a window’s position and size in terms of 
pixels, you could specify that the window was one-half the 
size of and centered within the client area of its parent win¬ 
dow; the user interface manager would then maintain this 
relationship as the user changed the size and position of the 
parent window. The WUIMAN framework knows very little 
about the user interface items it is manipulating, so it can 
store constraint equations just as easily as pixel offsets or 
anything else. 

if this sounds like a big project, it is. That makes C++ a 
good choice for implementing it. In general, I can reasonably 
create and maintain significantly larger programs with C++ 
than I can with C. This is mostly because C++ captures a 
higher-level description of my designs than C can, and the C++ 
compiler helps verify and record not just procedural specifica¬ 
tions, but more abstract entities and their relationships. I can 
expect more effort up front in designing the C++ program, but 
the payoff will come as I extend and maintain the software. 

Knuth apparently sat down and wrote TEX (a large page 
description language) roughly from start to finish before start¬ 
ing any debugging. Unfortunately, I lack both his patience and 
his coding self-confidence. When I start a big project, I try to 
come up with an early milestone that will either give me 
some confidence that I am on the right track, or an early 
warning that I’ve been derailed. Seeing the software do some¬ 
thing useful early on helps keep me enthusiastic — it’s more 
fun to add functionality to something that already does at 
least one useful thing than to write code day after day for a 
program that you've never been able to execute. 

The first milestone I set for WUIMAN is to get very simple 
menus implemented. I want to be able to write a program 
that creates a window and then lets WUIMAN manage the 
menu for that window, letting me interactively add, delete, 
and change menu items. Menus have to worry about fewer 
events than windows, but they are still fertile ground for im¬ 
provement. Eventually, it would be nice to have WUIMAN 
menu classes that automatically handle such things as 
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Figure 2 A Windows interface viewed as hierarchical tree 



context-sensitive help for menu items, 
most-recently-used file lists, interdepen¬ 
dent menu groups, and so on. Reaching 
this milestone will give me a good 
chance to see if the concepts I'm 
designing are really useful in real life. 1 
expect to get configurable menus up 
and running within three or four install¬ 
ments of this column. 


WUIMAN Objects 

Figure 1 provides a kind of vague 
overview of WUIMAN, but not nearly 
enough detail to start implementing 
anything. What is the structure of the 
WUIMAN database, in which it main¬ 
tains information about user interface 
objects? 

As I look at Windows programs’ user 
interfaces, I can view them as more or 
less hierarchical. There is usually a main 
window from which most aspects of 
the user interface descend. For ex¬ 
ample, to open a file, I typically go to the main window's 
menu (which can be viewed as a descendant of the main 
window), select File to view a submenu (a descendant of the 
main menu), and select Open to call up the common dialog 


for opening files. Figure 2 shows how you might view this kind 
of user interface as a hierarchical tree. 

A strict hierarchy is not such a good abstraction for the 
user interface, though. Take the case of the common dialog 
for opening files. You might want a single such window to 
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appear at more than one point in the user interface. A strict 
hierarchy doesn’t let me use the same window at different 
points in the tree. So, although I plan to organize the WUIMAN 
database as a hierarchical tree, the structure of the tree may 
not directly reflect the structure of the user interface. The 
hierarchy should work well for describing entities like menus, 
in which each submenu forms another child node on the tree. 
For windows, the hierarchy could describe the child-parent 
relationship that Windows itself maintains. In general, 1 expect 
the top level of the hierarchy will have quite a few nodes, 
including the main window, dialog boxes that may be invoked 
from multiple places in the interface, and anything else that 
doesn’t quite fit in as a descendant of some other part of the 
user interface. 

The hierarchical tree itself is probably not sufficient to 
describe the structure of the user interface, but it will be suffi¬ 
cient in conjunction with attributes. Each node in the WUIMAN 
hierarchical tree has a name, and (optionally) children, and 
(optionally) attributes. An attribute is an arbitrary piece of data 
that modifies the behavior of the node (user interface object) 
that owns it. For example, a button object might have a “Cap¬ 
tion” attribute, that the button object displayed as a text 
string on the button face. This sounds a lot like Visual Basic 
“properties,” but I am taking the XView approach instead, so 
WUIMAN object attributes really serve three purposes: proper¬ 
ties, events, and methods (using Visual Basic terminology). 

An example should help make this clear. Consider a simple 
pushbutton. In Visual Basic, it has a property called “Caption" 
that is the text string displayed on the button face. A Visual 
Basic program can get or set this property to inspect or 
change the text displayed on the button. The button also can 
generate a “Click” event. You can attach a Visual Basic proce¬ 
dure to this event, and it will get called when the user clicks 
the button. The Visual Basic button also supports a “Refresh" 
method. Your Visual Basic program can call this method to tell 
the button to redraw itself. 

WUIMAN (like XView) uses attributes to handle these three 
aspects of a pushbutton. WUIMAN attributes support two 
operations: get and set. A WUIMAN pushbutton might have a 
"Caption" attribute that functions almost exactly like a Visual 
Basic property. Instead of a “Click” event, it would have a 
“Click” attribute; you could set the attribute equal to one of 
the functions registered for handling this event, or get the 
“Click" attribute to inspect the name of the function currently 
assigned to handle that event. The WUIMAN button could 
have a “Refresh" attribute which, when set (not necessarily to 
any particular value), would cause the button to redraw itself. 
Getting the value of the “Refresh" attribute would probably 
just return zero, since I can't think of a meaning for that 
operation. 

Complexity is like a balloon: if you push hard on one side, 
it only bulges out somewhere else. Using the single concept of 
attributes instead of the three concepts of events, properties, 
and methods, does not really reduce the fundamental com¬ 
plexity of the problem. Setting and getting attributes works 
fine so long as no information other than the attribute name 
is required to specify the operation. For example, a WUIMAN 
object could support a “Refresh” attribute which, when set to 
one, invoked a refresh method that redrew the corresponding 


screen entity (window, for example). But what if you wanted 
to get the second line of text in a WUIMAN object repre¬ 
senting an edit control? The edit control text itself would 
probably be an attribute (named “Text," perhaps), but how 
could you specify that you wanted just the second line of 
text? 

XView handles the complexity of extra arguments by 
taking advantage of the fact that C can handle variable argu¬ 
ment lists. The basic XView get function is conceptually 
defined like this: 

Xv_opaque xv_get(Xv_object object, ...) 

In other words, you pass it a handle to an XView object, fol¬ 
lowed by arbitrary set of arguments. For example, you could 
get the dimensions of an XView window like this: 

Rect *rect; 

rect = xv_get(mywin, XV_RECT); 

XV_RECT is a symbolic constant that identifies a particular ob¬ 
ject attribute. You could get a section of text from a text sub¬ 
window with a call like this: 

xv_get(textwin, TEXTSW_CONTENTS, 
pos, buf, buflen); 

So, although XView is simple at the abstract level (you just 
have to understand getting and setting attributes), the details 
still pile up quickly in real life. I decided to use the unifying 
concept of attributes at the level of WUIMAN objects, but to 
present a style more akin to Visual Basic in the WUIMAN user 
interface. I will just use a simple naming convention to distin¬ 
guish properties from events from methods. 

One thing I wanted to do quite differently from XView was 
provide a string-based interface. With something like XView's 
xv_get(), which uses a variable argument list, the compiler 
cannot help you check for correct arguments or the correct 
return type, since it requires you to cast the return type into 
whatever type you were expecting for the particular attribute. 
Passing everything via strings is not much better, but at least 
the caller and the callee have a fighting chance to defend 
themselves against bad parameters or return values. Another 
motivation for a string-based interface is to avoid the kind of 
bugs endemic to Windows programming. WUIMAN never 
provides pointers to its data structures or requires an applica¬ 
tion to allocate and free WUIMAN resources. The interface to 
WUIMAN object attributes is this: 

long WUIMAN_Set(const char *Path, 
const char *Attribute, 
const char *Value); 
long WUIMAN_Get(const char *Path, 

const char ‘Attribute, char ‘Result, 
size_t ResultLength); 

Note the odd argument called Path, which specifies the 
WUIMAN object whose attribute you want to get or set. Just 
as a DOS path specifies a particular file in a hierarchy of files, 
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the WUIMAN path is a string that locates a particular WUIMAN 
object. For example, given a WUIMAN database structure like 
the tree in Figure 2, you might have a call like 

WUIMAN_Set("/MainWi n/Menu/Fi 1 e/Open", 

"Color", "red"); 

to set the File-Open menu item’s color to red (an operation 
not supported directly by the Windows API, but which I plan 
to provide in a WUIMAN class). 

Getting Started 

Rather than devote several columns solely to WUIMAN's 
design before starting any code, I want to intersperse the im¬ 
plementation with the design. This 
month, I want to present some of the 
building block code used to implement 
WUIMAN, to go along with the general 
introduction. The best place to begin is 
probably with a short explanation of 
my coding style. 

The usual goal for code I present in 
magazine articles is simplicity and 
brevity. The code in this column, how¬ 
ever, is part of a real, live program that 
I expect to have to maintain for quite 
some time, so it will reflect the coding 
style I use in real projects. I am not in¬ 
terested in converting anyone to this 
style (which changes fairly often 
anyway), only in pointing out the 
motivations behind it in hopes of to 
make it more readable. 

I use uppercase and lowercase to 
separate words that make up names; I 
use all uppercase for constants and 
macros. I prefix the names of C++ clas¬ 
ses with the letter “T", a habit I picked 
up from writing TPW code. The reason 
is that I often want to use the un¬ 
adorned name for variables. For ex¬ 
ample, l regularly run into code that 
manipulates a generic window, and the 
best variable name really is “Window"; 
that's not a conflict when the cor¬ 
responding class name is “TWindow”. 

One exception to this rule is abstract 
classes, which I prefix with “A” rather 
than “T”; for some reason, I’m more 
comfortable distinguishing these 
abstract classes from non-abstract clas¬ 
ses, even at the implementation level. 

Some of my coding practices relate 
to local readability — the ability, for ex¬ 
ample, to understand what a member 
function does without having to have 
its class definition at hand. I tend to 
tack a trailing underscore on to private 
data members so that I can easily iden¬ 


tify them; another reason is that I often have a member func¬ 
tion with the same name (sans trailing underscore) as the 
private data member. I am also not above using explicit this 
dereferencing, such as 

this->CallMember(/*...*/); 

just to remind myself that CallMemberf) is my own member 
function, in a particularly cluttered scope. Also in the name of 
local readability, I avoid using references as function 
parameters. When you read C code like this 

foo(x,45); 


finally, there are some 
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Listing 1 wuistd.h 
include this header 

— All WUIMAN source files 

lifndef WUISTD H 

Idefine WUISTD_H 


#include <assert.h> 
#include <stdlib.h> 


Idefine MEMBERASSERT() 
Idefine ASSERT assert 

(assert(this != 0)) 

// I prefer uppercase for this 

// ASSERT2 - when the asserted expression has required 
// side-effects. 

lifdef NDEBUG 

Idefine ASSERT2(exp) 
lei se 

Idefine ASSERT2(exp) 
lendif 

(exp) 

ASSERT(exp) 

// StringClone - allocate space for and duplicate a string, 
char *StringClone(const char *Input); 

lendif 

/* End of File */ 



you know that foo() does not modify x. Not so in C++, unless 
you choose, as I do, to follow a convention of avoiding refer¬ 
ence parameters. I do use const references where ap¬ 
propriate, however, since they have value semantics and do 
not disguise a potential modification of the caller’s parameter. 
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Listing 2 wuistd.c - General utility function 


linclude <string.h> 
linclude "wuistd.h" 

char *StringClone(const char * Input) 

I 

size_t Size = strlen(Input)+l; 
char 'Result « new charfSize]; 

ASSERT(Result != NULL); 
return (char *)memcpy(Result, Input, Size); 
) 

/* End of File */ 


wuistd.h 

When I'm building a large project, I usually have small 
header file that every other source file includes; wuistd.h 
(Listing 1) is that file for this project. Having such a file allows 
you to make a global change (such as redefining the global 
new operator) to all files easily, just by changing the common 
header file and recompiling. The conditional directive that sur¬ 
rounds the file ensures that no damage will be done if you 
include the file more than once, which can easily happen once 
you have a dozen or more interdependent header files in your 
project, wuistd.h defines an uppercase alias for the standard 
assert () macro, simply because I use a lot of assertions and 
like them to be visually distinct from ordinary code. MEM- 
BERASSERTf) is an assertion I tack on to every non-static class 
member function; it does a minor validity check on this. It 
may seem like a lot of extra clutter, but it has saved me 
enough time over the years that I no longer mind it. Windows 
can’t really protect itself or other applications from wild 
pointer problems, so the extra assertions help eliminate some 
of the tedious rebooting I associate with a long Windows 
programming session. 

wuistd.h also defines ASSERT2(), a macro to complement 
the standard assertion macro. When you compile with NDEBUG 
defined, assert.h redefines assert() so that it evaluates to 
an empty expression. That's useful so that the assertion code 
can be removed at will. Unfortunately, sometimes 1 want an 
assertion that has a side effect that I don’t ever want 
removed. This usually is a return value from a function that 
does something useful. For example, with the standard as¬ 
sert () macro, I might write: 

BOOL Status; 

Status = PostMessage(/*...*/); 
assert(Status != FALSE); 

This code says “I happen to know that PostMessage() is not 
going to fail, so I will assert that rather than check the return 
status.” In a case like this, I prefer to use the ASSERT2() 
macro (I’ve never thought of a good mnemonic name for it) in 
wuistd.h and write 

ASSERT2( 

PostMessage(/*...*/) 1= FALSE 

); 
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which eliminates the extra variable and 
has the advantage of supplying a more 
readable assertion message when the 
assertion fails, since it will display the 
entire function call, not just "Status != 
FALSE". 

This header file also serves as a 
dumping ground for general utility func¬ 
tions that don’t seem to have a good 
home elsewhere. The only such func¬ 
tion for this project so far is String- 
Clone (), which gives me a compiler-in- 
dependent function for cloning a given 
string. The implementation for String- 
Clone () is in wuistd.c (Listing 2). 



TWuiName 

As I mentioned earlier, WUIMAN offers a string interface to 
the outside world, and each WUIMAN object has a symbolic 
name, which is a string of characters. This scheme has the 
potential to be fairly inefficient in both space and speed. 
There will be a lot of these names, many the same, and they 
will be copied and compared frequently. What I need is a 
reference-counted string class, which I will call TWuiName. The 
idea is that each object of type TWuiName acts like a string 
externally, but internally contains a pointer to two items: the 


real string, along with a count that reflects how many other 
TWuiName objects are pointing to it. This attacks the space 
problem, since a string like “Font” (an attribute name that 
might appear many times in a WUIMAN database) need only 
be stored once, though it may be referenced by many TWui¬ 
Name objects. The reference-counting scheme also attacks the 
speed problem, since copying a TWuiName object only requires 
copying a pointer and incrementing a reference count, and 
comparing two TWuiNames for equality only requires compar¬ 
ing two pointers for equality. Figure 3 demonstrates reference 
counting by showing the results of the following declarations: 


Listing 3 wuiname.h - Declare class to handle 
WUIMAN object names 


#ifndef WUINAME_H 
Idefine WUINAME_H 

#ifndef WUISTD_H 

#include "wuistd.h" 
lendif 

class TWuiName 

( 

public: 

enum { MAXNAME = (64+1) ); 

TWuiName(const char *NewName=0); 

TWuiName(const TWuiName &0ther); 
const TWuiName& operator=(const TWuiName &0ther); 
~TWuiName(); 

int operator==(const TWuiName &0ther) const; 
int operator!=(const TWuiName &0ther) const; 
char *GetName(char ‘Buffer, 

int MaxLength=MAXNAME) const; 

private: 

short AtomHandle_; // Avoid disclosing it is an ATOM 

I; 

inline 

int TWuiName::operator==(const TWuiName &0ther) const 
{ MEMBERASSERTQ; 

return Other.AtomHandle_ == AtomHandle_; 

} 

inline 

int TWuiName: :operator! = (const TWuiName 8.0ther) const 

| MEMBERASSERTO; 

return !(*this == Other); 

} 

#endif 

/* End of File */ 
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Listing 4 wuiname.c — Implement class to handle 
WUIMAN object names 


linclude <string.h> 
linclude <windows.h> 
linclude "wuistd.h 11 
linclude "wuiname.h" 


// Constructor - convert string to TWuiName. 

TWuiName::TWuiName(const char *NewName) 

{ MEMBERASSERTO; 
if(NewName) 

( 

ASSERT(strlen(NewName) < MAXNAME); 

AtomHandle_ = (short)AddAtom(NewName); 

ASSERT(AtomHandl e_ != 0); 

) 

else 

AtomHandle_ = 0; 

) 

// Copy constructor - requires string copy. Gack! 

TWuiName::TWuiName(const TWuiName &0ther) 

( MEMBERASSERTO; 

char OtherName[MAXNAME]; 

if(Other.AtomHandl e_) 

{ 

A tomHandle_ = (short)AddAtom(Other.GetName(OtherName)); 
ASSERT(AtomHandle_ != 0); 

} 

el se 

AtomHandle_ = 0; 

) 

// Assignment - standard handle class concerns. 

const TWuiName &TWuiName::operator=(const TWuiName &0ther) 

( MEMBERASSERTO; 

if(&0ther != this) // account for self-assignment 
{ 

if(AtomHandle_) 

DeleteAtom((ATOM)AtomHandle_); 
if(Other.AtomHandl e_) 

( 

char OtherName[MAXNAME]; 

AtomHandle_ = (short)AddAtom(Other.GetName(OtherName)); 
ASSERT(AtomHandle_ != 0); 

) 

el se 

AtomHandle_ = 0; 

) 

return *this; 

} 

// Destructor - decrement reference count, delete if zero 
TWuiName::~TWuiName() 

{ MEMBERASSERTO; 
if(AtomHandle_) 

DeleteAtom((ATOM)AtomHandle_); 

1 

// GetName - convert TWuiName back into original string 
char ‘TWuiName::GetName(char ‘Buffer, int MaxLength) const 
{ MEMBERASSERTO; 

ASSERT(Buffer != 0); 

ASSERT(MaxLength >= 0); 
if(AtomHandle_) // if not NULL 

ASSERT2(GetAtomName((ATOM)AtomHandle_, Buffer, 

MaxLength) != 0); 

else 

‘Buffer = ' \0‘ ; 
return Buffer; 

} 

/* End of File */ 


TWuiName A("Menu"); 

TWuiName B("Menu"); 

TWuiName C( "Window"); 

As I was rushing to get a prototype done, it occurred to 
me that Windows already supplies me with reference-counted 
strings. If you look at Windows “atoms,” you will see that that 
is all they are. By using the Windows atom management func¬ 
tions, I had a TWuiName class running in short order. In my first 
pass, I did not implement copying operations for TWuiName. 
Only later, when I went back to implement the copy construc¬ 
tor and assignment operator, did I realize that a crucial func¬ 
tion is missing from the Windows atom management routines: 
you can decrement an atom’s reference count, but you can¬ 
not increment an atom’s reference count without actually al¬ 
locating the string that contains the atom’s name and passing 
it to AddAtom() again. I will have to go back eventually and 
replace this implementation of TWuiName with my own refer¬ 
ence-counting code in order to avoid doing string copies when 
copying TWuiName objects. 

wuiname.h (Listing 3) contains the declaration of TWuiName 
objects. Note that it declares the Windows atom handle as a 
short rather than an ATOM. I try to avoid forcing a user of my 
class to include windows.h unless it is really necessary. In this 
case, the implementation of TWuiName needs to access defini¬ 
tions in windows.h, but the interface does not, so I am willing 
to cast the short to an ATOM in the implementation code. 

The TWuiName declaration in wuiname.h is in what James 
Coplien calls “orthodox canonical form": it defines a default 
constructor, copy constructor, assignment operator, and 
destructor. These definitions make it safe to use a TWuiName 
object that you can declare, assign, and pass by value to 
other functions as though it were a built-in data type like an 
int. It also declares member functions const unless they 
modify the name contained in the TWuiName object. I generally 
avoid using overloaded operators, but in this case I relented 
because I expect comparing TWuiName objects to be such a 
common operation. 

TWuiName defines a constructor that takes a single argu¬ 
ment. Such constructors deserve scrutiny because they alter 
the type rules for your program. Since the constructor defined 
here takes a string argument, this means that the compiler 
will accept a string anywhere a TWuiName object is needed. 
For example, the following is legal code: 

extern int Foo(TWuiName Name); 
if(Foo("Menu")) 

II... 

Since TWuiName is conceptually a string itself, this implicit con¬ 
version makes sense in all the situations I can think of, but it’s 
a good idea to be aware that constructors can have this side 
effect. 

TWuiName defines an enumerator, MAXNAME, that is the 
longest name that TWuiName objects support. You might 
wonder why this is implemented as an enum rather than as a 
static const integer like this: 


Page 24 — Windows/DOS Developer’s Journal 


September 1993 




class TWuiName { 

II... 

static const int MAXNAME; 
private: 

II... 

This is one of those problems that remind you that C++ is a lan¬ 
guage with many nooks and crannies. The trick is, how do you 


define a TWuiName::MAXNAME variable? You might first try defining 
it in the header file, like your other const integer definitions: 

const int TWuiName::MAXNAME = 64+1; 

Unfortunately, static const class data members, unlike ordi¬ 
nary const entities, are global. For this reason, the linker com¬ 
plains that TWuiName: -.MAXNAME is multiply defined when you 


Listing 5 wuiargs.h — Define argument parsing for WUIMAN attributes 

#ifndef WUIARGS H 

TWuiArgs(const TWuiArgs& Dummy); 

Idefine WUIARGS H 

const TWuiArgs &operator=(const TWuiArgs&Dummy); 


const char *GetArg(const char ‘Input, char ‘Output); 

lifndef WUISTD H 

int NArgs ; 

linclude "wuistd.h" 

ArgType ArgTypes [MAXARGS]; 

lendif 

void *Args [MAXARGS]; 

#ifndef WUINAME H 

TWuiName AttributeName ; 

#include "wuiname.h" 

); 

#endif 



inline 

class TWuiArgs 

int TWuiArgs::NArgs() 

( 

{ MEMBERASSERT(); 

public: 

return NArgs ; 

enum ( MAXARGS = 16 } ; 

1 

TWuiArgs(const char ‘AttributeName); 


~TWuiArgs(); 

iniine 

enum ArgType { LONG ARG, STRING ARG, ERROR ARG ) ; 

TWuiName TWuiArgs::AttributeName() 

ArgType GetType(int Which); 

{ MEMBERASSERT (); 

long GetLong(int Which); 

return AttributeName ; 

char *GetString(int Which); 

i 

TWuiName AttributeName(); 


int NArgsf); 

lendif 

private: 

/* End of File */ 
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link two more more object files that included wuiname.h. The 
other alternative is to put the definition of TWuiName::MAX- 
NAME inside wuiname.c, as you would for a normal static data 
member. That certainly solves the problem of multiple defini¬ 
tions, but now suppose you want to include wuiname.h and 
then use this constant to declare a buffer size, as in: 

char Name[TWuiName::MAXNAME]; 
wuiname.GetName(Name); 

The compiler will object because it cannot determine at com¬ 
pile time what the value of TWuiName: -.MAXNAME is (it resides in 
wuiname.c and is not revealed in wuiname.h). For these 
reasons, a public enum is the solution, even though it really 
does not enumerate anything and a static const data mem¬ 
ber seems to be the natural choice. 

wuiname.c (Listing 4) contains the current implementation 
of the TWuiName class. Another example of the non-or¬ 
thogonality of the Windows atom API functions is the fact that 
they fail when passed an empty string. TWuiName treats a 
NULL atom handle as an empty string, which is the value used 
if you don't supply a string to initialize a TWuiName object. 

That’s about 100 lines of source code just to provide little 
more than a layer over the Windows atom-management func¬ 
tions. Is it worth the effort? Possibly not for small programs, 
but it is definitely worth the effort for a program the size of 
WU1MAN. It’s very easy to forget to delete a Windows atom 
and thereby create a resource leak that can eventually crash 
your program. The TWuiName class, however, largely removes 


that problem, making sure that every Windows atom that is 
created gets deleted. The exception is if you create a TWui¬ 
Name object with new and then don’t delete it. Since TWuiName 
objects are designed to have value semantics, there won’t be 
much need to allocate single TWuiName objects on the stack — 
no more than there typically would be to allocate a single int 
by calling new. Just as important, the implementation of object 
names is now isolated in one place. When I get around to 
replacing the calls to the Windows atom management func¬ 
tion with my own reference-counted strings, all the changes 
will lie within the TWuiName class, even though it is used in 
many other files. 

Parsing Arguments 

As I mentioned earlier, WUIMAN will have to be capable of 
accepting extra arguments when you get and set attributes. 
One concrete example of this is the WUIMAN user interface. I 
want to avoid giving the user interface special access to the 
WUIMAN database, in order to make it safe and easy for 
someone else to replace it with a different user interface. The 
WUIMAN user interface must therefore be able to traverse, 
examine, and modify the database, just using the standard get 
and set attribute functions. This will require extra arguments. 
For example, to get names of the children of a particular ob¬ 
ject in the hierarchical database, I expect to see code like this: 

char Name[TWuiName::MAXNAME]; 
sprintf(Attr, "Chi 1d(%d)", i); 

WUIMAN_Get('7MainWindow", Attr, Name, TWuiName::MAXNAME); 
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Listing 6 wuiargs.c — Implement argument parsing for WUIMAN attributes 

II wuiargs.c - implement argument parsing for WUIMAN set at- 

char Quote = *Input“; 

tribute 

char Next; 

// Copyright (c) 1993 by Ron Burk 

while((Next=*Input++) != ' \0 ') 

/ 

#include <ctype.h> 

i 

if(Next == Quote) 

#include <errno.h> 

if(‘Input == Quote) 

#include <string.h> 

“Input; // quoted quote char 

find ude <windows.h> 

else // else, end of quote 

/ 

linclude "wuiargs.h" 

‘Output = ' \0 '; 

// Getldentifier - extract token matching "[A-Za-z ] [A-Za-zO- 

char *Result = StringClone(Buffer); 

ArgTypes [NArgs ] = STRING ARG; 

9 ]*". 

Args [NArgs ] * Result; 

static 

return Input; // success! 

const char *GetIdentifier(const char *Input, char ‘Output) 

i 

{ 

*0utput“ = Next; 

if(isalpha(*Input) || ‘Input 1 ’) 

} 

( 

// must not have found end quote 

while(isalnum(*Input) || ‘Input »* ' ') 

return 0; 

*0utput++ = *Input++; 

i 

‘Output = 1 \0 ' ; 

else // else, try for integral arg 

return Input; 

{ 

i 

long LongArg; 

el se 

errno = 0; // I hate errno! 

return 0; 

LongArg = strtol(Input, &End, 0); 

) 

if(errno || (End == Input)) 

// EatWhite - skip over white space in the input stream. 

return 0; 

el se 

static 

( 

const char *EatWhite(const char ‘Input) 

Args [NArgs ] = (void *)new 1ong(LongArg); 

( 

ArgTypes [NArgs ] = LONG ARG; 

while(*Input && isspace(*Input)) 

return End; 

“Input; 

) 

return Input; 

) 

) 

) 

// Constructor - parse name and arg list 

// Destructor - free up memory 

TWuiArgs::TWui Args(const char ‘Input) 

TWuiArgs::~TWuiArgs() 

: NArgs (0), AttributeName (0) 

( MEMBERASSERTO; 

{ MEMBERASSERTO; 

if(NArgs > 0) 

char Name[TWuiName::MAXNAME]; 

{ 

char Token[256]; 

for(int i = 0; i < NArgs ; “i) 

Input = EatWhite(Input); 

if(ArgTypes_[i] == STRING_ARG) 
delete (char *)Args [i]; 

Input = Getldentifier(lnput, Token); 

el se 

if(!Input) return; 

delete (long *)Args [i]; 

Token[TWuiName::MAXNAME-1] = •\0 1 ; 

) 

strcpy(Name, Token); 

} 

Input = EatWhite(Input); 
if(‘Input) // something after attribute name 

// GetType - return type of a particular argument 

{ 

TWuiArgs::ArgType TWuiArgs::GetType(int Which) 

// it better be left paren 

{ MEMBERASSERTO; 

if(*Input++ != '(') return; 

if(Which >= 0 && Which < NArgs()) 

Input = EatWhite(Input); 

return ArgTypes [Which]; 

while(*Input && ‘Input != ')') 

else 

( 

return ERROR ARG; 

Input = GetArg(Input, Token); 

) 

if(!Input) return; 

Input = EatWhite(Input); 

// GetLong - return Nth argument as a long 

if(‘Input =* 1 ,') 

long TWuiArgs::GetLong(int Which) 

Input = EatWhite(++Input); 

( MEMBERASSERTO; 

“NArgs ; 

if(Which >= 0 && Which < NArgs()) 

} 

return *(long *)Args [Which]; 

if(*Input != ')') 

el se 

return; 

return 0; 

\ 

/ 

AttributeName = Name; 

/ 

i 

// GetString - return Nth argument as a string pointer 

// GetArg - helper function to extract string or long 

char ‘TWuiArgs::GetString(int Which) 

( MEMBERASSERTO; 

const char ‘TWuiArgs::GetArg(const char ‘Input, char ‘Buffer) 

if(Which >= 0 && Which < NArgsO) 

{ MEMBERASSERTO; 

return (char ‘)Args [Which]; 

char ‘Output * Buffer; 

else 

char ‘End; // can't use const because of strtol() 

return 0; 

‘Output = 1 \0 1 ; 

) 

if(*Input == '\" || ‘Input == 'V") 

{ 

/* End of File */ 
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In other words, when you get or set an attribute, a parameter 
list enclosed in parentheses can follow. 

Here is an informal grammar for the simple format of 
WUIMAN attributes: 

Attr -> Name Args 

Args -> ( Params ) 

| <null> 

Params -> ArgList 

| <nu11> 

ArgList -> ArgList , 

I Arg 

Arg -> STRING 

| NUMBER 

where NUMBER is any legal integer that will fit in a long and 
STRING is a quoted string, using either single or double quotes. 
C-style quote-doubling is supported, so the string "this isn't 
right" could be constructed either of the following ways: 

"This isn't right" 

'This isn''t right' 

I decided to create a class that accepts an attribute name 
(with a possible parameter list), parses it into its components, 
and then makes the components available via member func¬ 
tions. The result is TUuiArgs, in wuiargs.h (Listing 5) and 
wuiargs.c (Listing 6). The constructor parses the attribute 
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string, and the member functions let you inspect the number, 
types, and values of any parameters found. 

One odd aspect of this class is that it has a private copy 
constructor and assignment operator. I am following Rob 
Murray's advice here: since I don’t think this class will be 
copied or assigned to (the real reason is that I was in a hurry), 
I've made the copy constructor and assignment operator 
private, so that the compiler will complain of any attempt to 
copy or assign to an object of this class, except by friend or 
member functions. Furthermore, I haven't supplied a definition 
of either the copy constructor or the assignment operator, so 
if a friend or member function performs a copy or assign¬ 
ment, the linker will complain of an undefined function. The 
main point here is that the default copy and assignment 
operators are not appropriate for a class which contains 
pointers to heap memory —the default operators would leave 
you with two objects pointing to (and eventually trying to 
delete) the same memory. 

It is possible to mechanically translate a grammar into a 
parser that is guaranteed to accept precisely the language 
defined by the grammar. When you write an ad-hoc parser 
instead, as I've done here, you have to worry whether it really 
accepts the language you intended. In fact, there is at least 
one bug I didn't have time to fix in this parser that makes it 
accept illegal constructs —can you spot it? 

Summary 

I want to thank Bill Welch for encouraging me to look at X 
Window concepts in the context of this project. As usual, Paul 
Bonneau was an invaluable sounding board for various Win¬ 
dows implementation ideas. Next month's column will tackle 
building TUuiObject, the core class for defining the WUIMAN 
database, attributes, and user interface elements. 
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Windows NT Remote 
Procedure Calls 

Guy Eddon 


Windows NT was designed to support distributed computing, that is, the ability to 
distribute a single logical computing task across multiple physical computers con¬ 
nected to a network. One example of distributed computing in the PC market is a 
database server, such as that of Oracle. You can dedicate a machine on your net¬ 
work to running the database server; it “listens” for requests (such as an SQL query) 
from client applications connected to the network. To access the database server, 
you link your client application with a library supplied by the database server ven¬ 
dor. When your client application calls a library function (to retrieve a row from a 
table, for example), it appears to work just like a function call to any library. In 
reality, though, the library function is just a “stub" that packages up its parameters 
in some proprietary format, sends them across the network to the database server 
(which does all the hard work), and waits for a reply packet, which it then uses to 
return a status or any other information required by that particular function. 

No matter what the application, the mechanics of making calls to remote applica¬ 
tions look like local function calls will be similar. Function parameters must be 
placed into packets that can be sent across a network and delivered to the correct 
remote functions, then return values must make the return trip to the calling ap¬ 
plication. If the server does not respond in a reasonable amount of time, the client 
must treat this as an error or find another server on the network to satisfy the 
request. Since this aspect of distributed computing is the same for any distributed 
application, wouldn’t it be nice if the operating system provided a standard interface 
for this work? That is just one of the problems that the Windows NT Remote Proce¬ 
dure Call (RPC) mechanism solves. This article describes NT's RPC facilities and 
provides an example of distributed computing, in the form of a distributed applica¬ 
tion that uses multiple computers to compute prime numbers faster than a single 
CPU can. 


Guy R. Eddon is president of Guy Communications, Inc., a consulting firm specializing 
in Client/Server systems. Guy also teaches Windows NT courses for Learning Group 
International. He can be reached on CompuServe at 71172,1014. 
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ing TSRs as easy as a C or Assembly function call. 

• Extensive set of example that show the ease of writing 
TSR that run entirely in the background. 
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Listing 1 directio.c — 32-bit text-mode routines 


#include "directio.h" 

PutStruct(xl, yl, (char)(S D ? 201 : 218), 1, WHITE ON CYAN); 

PutStructjxl, y2, (char)(S D ? 200 : 192), 1, WHITE ON CYAN); 

HANDLE hStdOut; 

PutStruct(x2, yl, (char)(S D ? 187 : 191), 1, WHITE ON CYAN); 

CONSOLE_SCREEN_BUFFER_INFO csbi; 

PutStruct(x2, y2, (char)(S D ? 188 : 217), 1, WHITE ON CYAN); 

void set vid mem(void) { 


hStdOut • GetStdHandle(STD OUTPUT HANDLE); 

void clearscreen(W0RD attr) { 

GetConsoleScreenBufferInfo(hStdOut, &csbi); 

COORD Coord * { 0, 0 ); 

i 

Cons0utChar((char)32, 2000, attr); 

DWORD dummy; 


void mxyputs(UCHAR x, UCHAR y, char *str, unsigned attr) { 

char get character(int wait) { 

COORD Coord - { x , y }; 

HANDLE hStdln; 

WORD Col or[MAX STR]; 

DWORD dwInputMode, dwRead; 

unsigned count; 

INPUT RECORD alnputBuffer; 

WriteConsoleOutputCharacter(hStdOut, str, strlen(str), Coord, Sdummy); 

char chBuf; 

for(count - 0; count < strlen(str); count++) 

hStdln - GetStdHandle(STD INPUT HANDLE); 

Col or[count] = attr; 

GetConsoleMode(hStdIn, SdwInputMode) ; 

WriteConsoleOutputAttribute(hStdOut, Color, strlen(str). Coord, Sdummy); 

SetConsoleMode(h$tdIn, dwlnputModeS~ENABLE LINE INPUTS~ENABLE ECHO INPUT); 

' 

if(wait) { 

ReadFile(hStdIn, SchBuf, sizeof(chBuf), SdwRead, NULL); 

void mxyputc(UCHAR x, UCHAR y, char ch, UCHAR num, UCHAR attr) ( 

SetConsoleMode(hStdIn, dwInputMode); 

COORD Coord « { x, y ); 

return chBuf; 

ConsOutChar(ch, num, attr); 

i 

i 

else { 

PeekConsoleInput(hStdIn, SalnputBuffer, 1, Sdummy); 

void box(UCHAR xl, UCHAR yl. UCHAR x2, UCHAR y2, char S D) { 

SetConsoleMode(hStdIn, dwInputMode) ; 

COORD Coord; 

FIushConsolelnputBuffer(hStdln) ; 

UCHAR count; 

if(alnputBuffer.EventType == KEY EVENT) 

forfeount - yl + 1; count < y2; count++) { 

return (char)(alnputBuffer.Event.KeyEvent.wVirtualKeyCode); 

PutStruct(xl, count, (char)(S D ? 186 : 179), 1, WHITE ON CYAN); 

) 

PutStruct(x2, count, (char)(S_D ? 186 ; 179), 1, WHITE ON CTAN); 

i 

count = x2 - x1 - 1; 

/* End of File *7 

PutStruct(xl+l ,yl, (char)(S D ? 205 : 196), count, WHITE_ON_CYAN); 

PutStruct(xl+l ,y2, (char)(S_D ? 205 : 196), count, WHITE_0N_CYAN); 



RPC: The Foundation of Distributed Computing 

Applications that use remote procedure calls are inherently 
distributed. Such applications are usually divided into two 
parts: a client and a server. The client always make requests 
of the server, whose only purpose is to provide the client with 
whatever information it requests. You can classify such ser¬ 


vers by the type of resource they offer. For instance, vendors 
already offer file servers, print servers, and communication 
servers. Windows NT makes it possible for a server to share 
not only its peripherals, such as hard disk space, printers, and 
modems, but also its computational horsepower, via compute 
servers. 
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Listing 2 directio.h - Header file for directio.c 


linclude <stdio.h> 
linclude <string.h> 

#include <stdlib.h> 

#include <stdarg.h> 
linclude <limits.h> 
linclude <ctype.h> 
linclude <windows.h> 
linclude <rpc.h> 
linclude "prime.h" 

Idefine BACKGROUND CYAN (WORD)0x0030 

Idefine NO WAIT 0 

Idefine TEST XI 3 

Idefine TEST Y1 3 

Idefine TEST X2 23 

Idefine TEST Y2 18 

Idefine PRIME XI 30 

Idefine PRIME Y1 3 

Idefine PRIME X2 50 

Idefine PRIME_Y2 18 

Idefine Cons0utChar(l, c, z) FillConsole0utputCharacter(hStd0ut, 1, c,\ 

Idefine WHITE ON BLUE 

(W0RD)0x0007|(WORD)0x0008|(WORD)OxOOlO 

Coord, &dummy); FillConsole0utputAttribute(hStd0ut, z, c. Coord,\ 

Idefine WHITE ON CYAN 

{W0RD)0x0007j(W0RQ)0x0008|(W0RD)0x0030 

&dummy) 

Idefine RED ON BLUE 

(W0RD)0x0O04j(W0RD)0x0008|(WORD)OxOOlO 

Idefine CoordStruct(x, y) Coord.X * x, Coord.Y = y 

Idefine RED ON CYAN 

(WORD)0x0004 | (WORD)0x0008|(WORD)0x0030 

Idefine PutString(x, y, clr, frmt, varl, var2) { sprintf(Buffer, frmt, varl,\ 

Idefine CYAN ON CYAN 

{W0RD)0x0003j(WORD)Ox0030 

var2); mxyputs ( (UCHAR)(x), (UCHAR)(y), Buffer, clr); ) 

Idefine SINGLE 

0 

Idefine PutStruct(x, y, 1, c, z) CoordStruct(x, y); Cons0utChar(l, c, z); 

Idefine DOUBLE 

1 

Idefine CheckStatus(comment) if(status) { printf("comment %d\n");\ 

Idefine MAX STR 

100 

exit(status); } 

Idefine PRIME 

Idefine NOT PRIME 

1 

0 

extern HANDLE hStdOut; 

Idefine MAX CALLS 

10 

extern CONSOLE SCREEN BUFFER INFO csbi; 

Idefine ERROR EXIT 

2 

extern void clearscreen(WORD), box(UCHAR, UCHAR, UCHAR, UCHAR, char); 

Idefine SUCCESS EXIT 

0 

extern void mxyputs(UCHAR, UCHAR, char *, unsigned); 

Idefine STRING LENGTH 

256 

extern void mxyputc(UCHAR, UCHAR, char, UCHAR, UCHAR), set vid mem(void); 

Idefine WAIT 

350 

extern char get character(int); 

Idefine WAIT DISPLAY 
Idefine C N LENGTH 

2000 

7 

/* End of File */ 


If you were to measure the percentage of resources used 
on most networks over a period of a month, you would 
probably determine that the network was busy about 10 to 
15 percent of that time. The number of wasted CPU cycles is 
enormous. Using RPC, you can take advantage of this wasted 
processing power by distributing work across the network to 


all available compute servers. Compute servers do not neces¬ 
sarily have to be locked in a room with the file server, since 
any computer on the network running Windows NT can be 
considered a compute server. If it is not currently working at 
full capacity, then work can be sent to it from another com¬ 
puter that is overloaded. 
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Distributed systems offer many advantages over more con¬ 
ventional centralized systems. In a centralized system, upgrad¬ 
ing the main computer is difficult at best. Sometimes the en¬ 
tire computer must be replaced with a more powerful one. 
This requires that the current system be brought down and 
replaced before the new one can be used. During that period 
all the users who depend upon those systems are out of luck. 
In a distributed system, upgrading often consists of merely 
adding another computer to the network. For most users, the 
only noticeable effect is that their work gets processed faster. 
In addition, distributed systems are more fault tolerant than 
centralized ones. In a centralized system, if the main com¬ 
puter goes down, the users go down. A failure in a properly 
constructed distributed system causes at most a few resour¬ 
ces and some computing power to be 
temporarily unavailable. A successful 
distributed system results in an ex¬ 
ponential increase in available com¬ 
putational power. 

While client/server architecture of¬ 
fers many benefits, it also extracts a 
price in complexity. Systems built using 
this paradigm are usually much more 
complex, and often require longer to 
develop. They are also more apt to 
have reliability problems than their 
centralized counterparts. RPC was 
designed to directly address these is¬ 
sues. 

Microsoft RPC is compatible with the 
Open Software Foundation (OSF) Dis¬ 
tributed Computing Environment (DCE). 

This allows it to interoperate with DCE 
servers and any other RPC tool com¬ 
patible with the OSF DCE standards. The 
low-level network communication done 
to facilitate the remote procedure call 
mechanism is implemented in a 
hardware independent manner. The RPC 
run-time module can communicate in 
many standard network protocols. 

Microsoft RPC even deals with the dif¬ 
ferent “endian” schemes found on some 
computers. Even IBM has announced an 
OSF DCE compatible environment for 
OS/2 2.0, meaning that Windows NT ap¬ 
plications may soon be able to call 
remote procedures running under OS/2. 

All things considered, RPC is a very 
powerful tool for communication and 
distribution. 

The Design and Purpose of RPC 

Remote procedure calls are designed 
to alleviate the difficulties commonly 
associated with building distributed ap¬ 
plications. These difficulties consist of all 
the possible errors that can occur in ap¬ 
plications that communicate over a net¬ 


work. When an application sends a message to another ap¬ 
plication, such as a DDE message, that application can be 
reasonably sure that the other application will receive it. How¬ 
ever, even with DDE, a lot of programming effort is focused on 
error handling. What if the application engaged in the conver¬ 
sation does not follow the DDE protocol properly? What if it 
crashes? What if it sends garbage? These types of problems 
increase exponentially when communicating over a network. 
As anyone who has ever done low-level network program¬ 
ming knows, the number of errors that can occur is mind-bog¬ 
gling. Someone can trip over the network cable, the server 
can crash, an application can fail to acknowledge a message. 
When working with network communication the following 
rule of thumb applies: if it can go wrong, it will. 
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Listing 3 client.c — Client side of prime number application 

llnclude "directlo.h" 

status - RpcBindingFromStringBinding(pSBind[i], &BindHandle[i]); 
CheckStatus(RpcBindingFromStringBinding); 

Idefine MAX THREADS 9 

i 

Idefine REMOTE TRY 100000 

) 


else { 

extern void thread local(void), thread remote(1nt), thread client(void) ; 

printf("\n\n\tC0MPUTING LOCALLY ONLY!\n\n\tFor Server Specify:\n M ); 

extern void Usage(void); 

printf ( 

extern char ServerStatus(char) ; 

"\t -n networkaddress (client -n \\\\serverl;\\\\server2;..)\n") ; 
get character(WAIT); 

PCONTEXT HANDLE TYPE phContext[MAX THREADS]; 

i 

HANDLE hthread client, hthread remote[MAX THREADS]; 

GetComputerName(comp name, &Max CompName Length); 

CRITICAL SECTION GlobalCriticalSection; 

InitializeCritical Section(SGlobalCritical Section); 

UCHAR pszRName[MAX THREADS][STRING LENGTH], IsPrime(ULONG TestNumber); 

for(i = 0; i < ipszNetAdd; i++) 

ULONG IDThrdClient, StartNumber - 1, Notry[MAX THREADS]; 

ULONG PrimeSHandle[MAX THREADS], NoPrimeRemotelMAX THREADS]; 

ServerStatus ( (char)i ); 

for(count = 1; count <* ipszNetAdd ; count++) 

ULONG NextNumber - 1, StartTime, CurrTime, NoPrimeLocal, NoPrimeRemoteT; 

hthread remote[count-l] = CreateThread(NULL, 0, 

WORD Col or[TEST X2-TEST Xl-3], Normal[TEST X2-TEST Xl-3]; 

(LPTHREAD START ROUTINE)thread remote, count, 0, &IDThrd[count-l] ) ; 

SMALL RECT pRectTest = ( TEST Xl+l, TEST Yl+2, TEST X2-1, TEST Y2-1 }; 

set vid mem(); 

SMALL RECT pRectPrime - { PRIME Xl+1, PRIME Yl+2, PRIME X2-1, PRIME Y2-1 }; 

clearscreen(BACKGROUND CYAN); 

COORD coordTest - { TEST Xl+1, TEST Yl+1 }; 

StartTime * GetTickCount() ; 

COORD coordPrime - { PRIME Xl+1, PRIME Yl+1 }; 

box(0, 0, 79, 24, DOUBLE); 

CHAR INFO pchiFill - ( (char)32, WHITE ON BLUE ); 

mxyputs(37, 0, * CLIENT ", WHITE ON CYAN); 

COORD ComputTestCoord « { TEST X2-7, TEST Y2-1 }; 

mxyputs(TEST XI, 2, “Testing..,", WHITE ON CYAN); 

COORD ComputPrimeCoord - ( PRIME X2-7, PRIME Y2-1 ); 

box(TEST XI, TEST Yl, TEST X2, TEST Y2, SINGLE); 

DWORD dummy; 

mxyputs (PRIME XI, 2, "Prime!", WHITE ON CYAN); 

int IpszNetAdd - 0, NumThreads, count, i; 

box(PRIME XI, PRIME Yl, PRIME X2, PRIME Y2, SINGLE); 

char IsActIveServer[MAX THREADS], comp name[STRING LENGTH]; 

mxyputs(32, 23, "Press Esc to exit", WHITE ON CYAN); 

handle_t BindHandle[MAX_THREADS]; 

hthread client = CreateThread(NULL, 0, 

(LPTHREAD START ROUTINE)thread client, NULL,CREATE SUSPENDED, 

void CRTAPI1 ma1n(1nt argc, char **argv) { 

AIDThrdCllent); 

RPC STATUS status; 

SetThreadPriority(hthread client, THREAD PRIORITY NORMAL); 

UCHAR *pUuid ■ NULL, *pProtocolS ■ "ncacn np"; 

ResumeThread(hthread client); 

UCHAR *pOpts - NULL, *pS8ind[MAX THREADS] - ( NULL ); 

thread local(); 

UCHAR *pNetworkA[MAX THREADS] - { NULL }; 

DeleteCriticalSection(&G1obalCriticalSection); 

UCHAR pEndp[MAX THREADS][STRING LENGTH]; 

if(pNetworkA[0]) 

DWORD Max CompName Length - STRING LENGTH, IDThrd[MAX THREADS]; 

for(count - 0; count < ipszNetAdd; count++) 

char tokensep[] - " \t,;", *token; 

if(RpcStringFree(&pSBind[count])) 

Int loop; 

exit(ERROR EXIT); 

for(loop * 0; loop < TEST X2-TEST Xl-3; loop++) { 

exit(SUCCESS EXIT); 

Color[loop] * RED ON BLUE; 

) 

Normal[loop] - WHITE ON BLUE; 


) 

void thread local(void) { 

for(count ■ 0; count < MAX THREADS; count++) 

ULONG temp; 

strcpy(pEndp[count], "\\pipe\\prime"); 

char Buffer[STRING LENGTH]; 

for(count ■ 1; count < argc; count++) { 

while(l) { 

If((*argv[count] — '-') || (*argv[count] “ '/')) { 

EnterCri ti cal Section(&G1obalCriticalSection); 

switch(tolower(*(argv[count]+l))) { 

if((temp * ++NextNumber) >= ULONG MAX) 

case 'p': /* protocol sequence */ 

break; 

pProtocolS ■ argv[++count]; 

ScrollConsoleScreenBuffer(hStdOut, SpRectTest, NULL, coordTest, 

break; 

&pchiFill); 

case 'n': /* network address */ 

PutString(TEST Xl+2, TEST Y2-1, WHITE ON BLUE, "%d", temp-1, ""); 

token - strtok(argv[++count], tokensep); 

WriteConsoleOutputAttribute(hStdOut, Normal, 7, ComputTestCoord, 

while(token 1- NULL) { 

&dummy); 

pNetworkA[ip$zNetAdd] « token; 

mxyputs((UCHAR)(TEST X2-7), (UCHAR)TEST Y2-1, "LOCAL ", WHITE ON BLUE); 

token * strtok(NULL, tokensep); 

LeaveCriticalSection(&G1obalCritical Section); 

strcpy(pszRName[ipszNetAdd], 

if(IsPrime(temp - 1) !* 0) { 

strupr(&pNetworkA[ipszNetAdd][2])); 

EnterCri tical Section(&G1 obalCriticalSection); 

pszRName[ipszNetAdd][C N LENGTH] - 0; 

ScrollConsoleScreenBuffer(hStdOut, SpRectPrime, NULL, coordPrime, 

printf(" (*d) - *s\n", ipszNetAdd + 1, 

&pchiFill); 

pNetworkA[ipszNetAdd]); 

PutString(PRIME Xl+2, PRIME Y2-1, WHITE ON BLUE, “%-I7d”, temp-1, 

ipszNetAdd++; 

M ); 

} 

WriteConsoleOutputAttribute(hStdOut, Normal, 7, ComputPrimeCoord, 

printf("\n Please wait.\n M ); 

&dummy); 

break; 

mxyputs((UCHAR)(PRIME X2-7), (UCHAR)PRIME Y2-1, "LOCAL ", 

case 1 e': /* endpoint */ 

WHITE ON BLUE); 

token ■ strtok(argv[++count], tokensep); 

LeaveCriticalSection(&G1obalCriticalSection); 

while(token 1- NULL) { 

NoPrimeLocal++; 

strcpy(pEndp[ipszNetAdd], token); 

i 

token - strtok(NULL, tokensep); 

) 

printf("%d %s\n", ipszNetAdd, pEndp[ipszNetAdd]); 

i 

ipszNetAdd++; 


i 

void thread remote(int count) { 

break; 

ULONG temp; 

case 1 f': /* first number */ 

char Buffer[STRING LENGTH]; 

NextNumber ■ StartNumber ■ atol(argv[++count]); 

while(l) { 

break; 

if(!IsActiveServer[count-l]) { 

default: 

if(Notry[count-1]++ > REMOTE TRY) ( 

Usage(); 

mxyputs((UCHAR)10, (UCHAR)21, 

i 

"Attempting to connect to Prime Server:", WHITE ON CYAN); 

i 

mxyputs((UCHAR)49, (UCHAR)21,pszRName[count-l], WHITE ON CYAN); 

else 

Notry[count - 1] - 0; 

Usage(); 

EnterCriticalSection(&G1obalCriticalSection); 

i 

ServerStatus((char)(count - 1)); 

if(pNetworkA[0]) { 

LeaveCri ti cal Secti on (&G1 obal Cri ti cal Secti on); 

for(i ■ 0; i < IpszNetAdd; i++) { 

mxyputc(10, (UCHAR)(21), (char)32, 48, CYAN ON CYAN); 

status ■ RpcStringBindingCompose(pUuid, pProtocolS, pNetworkA[i], 

) 

pEndp[i], pOpts, &pSBind[i]); 

else 

CheckStatus(RpcStringBindingCompose); 

continue; 

/* Set the binding handle that will be used to bind to the server */ 

i 

if(!IsActiveServer[count-l]) 

for(i ■ 0; i < ipszNetAdd; i++) { 

continue; 
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RPC addresses these problems by providing a procedural 
interface to the network. Without such an interface, dis¬ 
tributed computing is centered on the problem of I/O. Central¬ 
ized systems, however, were not built upon I/O, but rather on 
a procedural foundation. RPC solves this by providing a facility 
to build distributed systems based on the procedural model of 


Listing 3 continued 


EnterCriticalSection(&G1obalCriticalSection); 

If((temp - ++NextNumber) >« UL0NG_MAX) 
break; 

ScrollConsoleScreenBuffer(hStdOut, &pRectTest, NULL, coordTest, 

&pchiFill); 

PutString(TEST_X1+1, TEST_Y2-1, RED_ON_BLUE," %-17d\ temp-1, " N ); 
WriteConsoleOutputAttribute(hStdOut, Color, 7, ComputTestCoord, 

&dummy); 

mxyputs((UCHAR)(TEST_X2-7), (UCHAR)TEST_Y2-1, pszRName[count-l], 

RED _ 0N _ BLUE )J 

LeaveCritical Section(&G1obalCriticalSection); 

RpcTryExcept { 

if(RemoteIsPrime(BindHandle[count-l], PrimeSHandle[count-l], 
temp - 1) 1-0) { 

EnterCritical Section(&G1 obal Cri ticalSecti on); 
ScrollConsoleScreenBuffer(hStdOut, &pRectPrime, NULL, 
coordPrime, &pchiFI11); 

PutString(PRIME_Xl+l, PRIME_Y2-1, RED_0N BLUE, M %-17d", temp-1, 

WriteConsoleOutputAttribute(hStdOut, Color, 7, ComputPrimeCoord, 
&dummy); 

mxyputs((UCHAR)(PRIME_X2-7), (UCHAR)PRIME_Y2-1, 
pszRName[count-l], RED_ON_BLUE); 

LeaveCri ticalSection(&G1obalCritical Section); 

NoPrimeRemote[count-1]++; 

NoPrimeRemoteT++; 

} 

} 

RpcExcept(l) { 

EnterCriticalSection(&G1obalCriticalSection); 

ServerStatus((char)(count - 1)); 

LeaveCriticalSection(&G1obalCriticalSection); 

i 

RpcEndExcept 

i 

t 

UCHAR IsPrime(ULONG TestNumber) { 

ULONG count. HalfNumber * TestNumber / 2 + 1; 
for(count - 2; count < HalfNumber; count++) 
if(TestNumber H count »■ 0) 
return N0T_PRIME; 
return PRIME; 

} 

void Usage(void) { 

printf("Usage: CLIENT\n"); 
printf(" -p protocol_sequence\n"); 

printf(" -n network_address (\\\\serverl;\\\\server2;..An"); 
printf(" -e endpoint\n"); 
printf(" -f first number\n"); 
exit(l); 

} 

char ServerStatus(char iserver) ( 
char value - FALSE; 

RpcTryExcept { 

PrimeSHandle[iserver] * InitPServer(BindHandle[iserver], 

&phContext[iserver], compjiame); 

IsActiveServer[iserver] * TRUE; 

} 

RpcExcept(l) { 
value - TRUE; 

IsActiveServer[iserver] ■ FALSE; 

} 

RpcEndExcept 
return value; 

} 

void thread_client(void) { 

UCHAR no_active - 0; 
while(l) { 

char Buffer[STRING_LENGTH]; 
int i; 

if(VK_ESCAPE -- get_character(NO_WAIT)) { 

EnterCriti cal Section(&G1obalCriticalSection); 

Sleep(WAIT); 

for(i = 0; i < ipszNetAdd; i++) { 

RpcTryExcept { 
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its centralized ancestors. Figure 1 shows an overview of the 
RPC mechanism. 

The goal of RPC in action is to be as transparent and un¬ 
obtrusive as possible. The remote procedure call model at¬ 
tempts to adhere closely to the normal local procedure call 


model. It accomplishes this so well, in fact, that even a 
programmer need not know if a function will execute remote¬ 
ly or locally. This is made possible by a special RPC language 
called the Interface Definition Language (IDL). 


Listing 3 continued 


TerminatePServer(BindHandle[i], PrimeSHandle[i]); 

} 

RpcExcept(l) { 
clearscreen(O); 
exit(O); 

} 

RpcEndExcept 

} 

clearscreen(O); 
exlt(O); 

LeaveCriticalSection(&G1 obalCritical Secti on); 

} 

mxyputs(58, 2, "Number of Primes", WHITE_ON_CYAN); 

PutString(60, 4, WHITE_ON_CYAN, "%s:%5d", "LOCAL ", NoPrimeLocal); 
EnterCriticalSection(&G1obalCritical Section); 
for(no active * i ■ 0; i < ipszNetAdd; i++) 
if(IsActiveServer[i]) 

PutString(59, 5+no_active++, RED_0N_CYAN, " %7s:%5d ", pszRName[i], 
NoPrimeRemote[i]); 

box(58, 3. 74, (UCHAR)(5+no_active), SINGLE); 
mxyputc(58, (UCHAR)(6+no_active), (char)32, 17, CYAN_0N_CYAN); 
for(no_active ■ i * 0; i < ipszNetAdd; i++) 
if(1IsActiveServer[i]) 

PutString(59, 19+no_active++, RED_ON_CYAN," %7s:%5d ", pszRName[i], 
NoPrimeRemote[i]); 
if(no_active) { 

mxyputs(58, (UCHAR)(17), "Inactive Servers", WHITEONCYAN); 
box(58, (UCHAR)(18), 74, (UCHAR)(19+no_active), SINGLE); 
mxyputc(58, (UCHAR)(20 + no_active), (char)32, 17, CYAN_0N_CYAN); 

} 

else 

for(i - 0; 1 < 5; i++) 

mxyputc(58, (UCHAR)(17+no_active+i), (char)32, 17, CYAN_0N_CYAN); 
LeaveCri ti cal Secti on (&G1 obal Cri ti cal Secti on); 

CurrTime ■ (GetTickCount() - StartTime) / 1000; 

PutString(58, 7+ipszNetAdd, WHITE_0N_CYAN, "Primes « %d", 

NoPrimeLocal+NoPrimeRemoteT, ""); 

PutString(58, 8+ipszNetAdd, WHITE_0N_CYAN, "Time - %d.%02d min.", 
CurrTime/60, CurrTime%60); 

PutString(58, 9+ipszNetAdd, WHITE_0N_CYAN, "First » %d", StartNumber, 

) 

} 

/* End of File */ 


Listing 4 server.c — Server side of prime number 
application 


♦include "directio.h" 

extern char IsPrime(UL0NG TestNumber), GCompName[MAX_CALLS][STRING_LENGTH]; 
extern void Usage(void), thread_server(void); 
extern UL0NG NoPrimes[MAX_CALLS], handles; 

DWORD IDThrd; 

HANDLE hthread_server; 

CRITICAL_SECTI0N Global Critical Section; 

void CRTAPI1 main(int argc, char *argv[]) { 

RPC_STATUS status; 

UCHAR "pProtocolS ■ "ncacn_np", "pSecurity * NULL, 

"pEndp - "WpipeWprime"; 
unsigned cMinCalls - 1, cMaxCalls ■ MAX_CALLS, i; 
for(i - 1; (int)i < argc; i++) { 

1f((*argv[i] — '-') || (*argv[i] « '/')) { 
switch(tolower(*(argv[i]+l))) { 
case 'p': 

pProtocolS - argv[++i]; 
break; 
case 'e': 

pEndp * argv[++i]; 
break; 
default: 

Usage(); 

} 

} 


Listing 4 continued 


else 

Usage(); 

} 

status * RpcServerUseProtseqEp(pProtocolS, cMaxCalls, pEndp, pSecurity); 
CheckStatus(RpcServerUseProtseqEp); 

status - RpcServerRegisterlf(prime_ServerIfHandle, NULL, NULL); 
CheckStatus(RpcServerRegisterlf); 

InitializeCriticalSection(&GlobalCriticalSection); 
set vid mem(); 

cl earscreen(BACKGR0UND_CYAN); 
box(0, 0, 79, 24, DOUBLE); 
mxyputs(37, 0, " PRIMES ", WHITEONCYAN); 
mxyputs(TEST_X1, 2, "Testing...", WHITE_0N_CYAN); 
box(TEST_Xl, TEST_Y1, TEST_X2, TEST_Y2, SINGLE); 
mxyputs(PRIME_X1,~2, "Prime!", WHITE_0N_CYAN); 
box(PRIME XI, PRIME_Y1, PRIME_X2, PRIME_Y2, SINGLE); 
mxyputs(32, 23, "Press Esc to exit", WhTtE_ 0N_CYAN); 
hthread_server = CreateThread(NULL, 0, 

(LPTHREAD_START_R0UTINE)thread_server, NULL, CREATE_SUSPENDED, 
&IDThrd);“ 

SetThreadPriority(hthread_server, THREAD_PRI0RITY_L0WEST); 
ResumeThread(hthread_server); 

mxyputs(23, 21, "Listening for prime number requests.", RED_0N_CYAN); 
status ■ RpcServerListen(cMinCalls, cMaxCalls, FALSE); 

CheckStatus(RpcServerListen); 

} 

void Usage(void) { 

printf("Usage: SERVER\n"); 
printf(" -p protocol_sequence\n"); 
printf(" -e endpoint\n"); 
exit(EXIT_SUCCESS); 

} 

void _RPC_FAR *_RPC_API midl_user_allocate(size_t len) { 

return(mal1oc(1en)); 

} 

void _RPC_API midl_user_free(void _RPC_FAR *ptr) { 

free(ptr); 

} 

void thread_server(void) { 
while(l) { 

char Buffer[STRING_LENGTH], Buffert[STRING_LENGTH]; 

UCHAR i; 

if(VKESCAPE -- get_character(N0_WAIT)) { 

EnterCriticalSection(&G1 obalCriticalSection); 

Sleep(WAIT); 
clearscreen(O); 
exit(EXIT_SUCCESS); 

LeaveCriticalSection(&G1obalCriticalSection); 

DeleteCritical Section(&G1obalCriticalSection); 

} 

if(handles) { 

mxyputs(58, 2, "Number of Primes", WHITE_0N_CYAN); 

EnterCritical Section(&G1obalCritical Section); 
for(i - 0; i < handles; i++) { 

strncpy(Buffert, strupr(GCompName[i]), C_N_LENGTH); 

Buffert[C N_LENGTH] - 0; 

PutString"(59, 4+i, WHITE_0N_BLUE, " %7s:%5d ", Buffert, 

NoPrimes[i]); 

} 

box(58, 3, 74, (UCHAR)(4 + handles), SINGLE); 
mxyputc(58, (UCHAR)(5+i), (char)32, 17, CYAN_0N_CYAN); 

LeaveCriticalSection(&G1obalCritical Section); 

} 

else 

for(i - 0; i < 13; i++) 

mxyputc(58, (UCHAR)(2+i), (char)32, 17, CYAN_0N_CYAN); 
if(lhandles) { 

mxyputs(23, 21, "Listening for prime number requests.", 

RED_0N CYAN); 

Sleep(WAIT DISPLAY); 

} 

mxyputc(23, 21, (char)32, 36, CYAN_0N_CYAN); 

} 

} 

/* End of File */ 
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Interface Definition Language 

The Interface Definition Language (IDL) is a language that 
lets you define the interface between a client and a server. 
Once the interface is defined, all the communication between 
the client and the server passes through it. In projects involv¬ 
ing communications between applications written by different 
teams, the problem is to define a common interface to which 
both sides will adhere. With IDL, this process is automated. 
Once the interface has been defined with IDL, both sides must 
adhere to it, or they will not be able to compile their 
programs. 

In an IDL definition file you specify the name, version, and 
UUID of the interface. The ULIID, or Universally Unique I- 
Dentifier, is a special number that the RPC runtime code uses 
to ensure it sends remote procedure calls to the correct serv¬ 
er (the UUID of the server must match that of the client). Be¬ 


sides identification information, you also place in the IDL 
definition file a prototype for each function that the server 
exports. 

You compile an IDL file with a special compiler, the 
Microsoft Interface Definition Language (MIDL) compiler, which 
translates the IDL description into C. The C code generated by 
MIDL forms the remote procedure stubs in both the client and 
the server. Thus the master IDL file produces code that is 
compiled and linked in by both sides of the distributed ap¬ 
plication. If one side does not follow the specified interface, 
the compilation or link will fail. 

Binding 

Binding is the mechanism by which the client connects to the 
server at runtime. Since the server resides on a separate machine, 
there is no way at compile time for the client application to 


Listing 5 remote.c — Server support routines 


linclude "directio.h" 

WriteConsoleOutputAttribute(hStdOut, Local, C N LENGTH, 

ComputTestCoord, &dummy); 

extern CRITICAL SECTION GlobalCriticalSection; 

LocalCompName[C N LENGTH] - 0; 


mxyputs ( (UCHAR)"fTEST X2-7), (UCHAR)TEST Y2-1, LocalCompName, 

ULONG handles - 0, handlesp ■ 0, handle mod * 1, NoPrimes[MAX CALLS]; 

WHITE ON BLUE); 

ULONG GlobalComputerHandleBuffer[MAX CALLS]; 

LeaveCriticalSection(&G1obalCritical Section); 

char GCompName[MAX_CALIS][STRING_LENGTH]; 

for(count - 2; count < HalfNumber; count++) 
if(TestNumber % count *■ 0) 

ULONG InitPServer(handle t hi, PPCONTEXT HANDLE TYPE pphContext, 

return NOT PRIME; 

UCHAR "CompName) { 

EnterCriticalSection(&G1obalCritical Section); 

ULONG unique handle; 

ScrolIConsoleScreenBuffer(hStdOut, ApRectPrime, NULL, coordPrime, 

char Buffer[STRING LENGTH]; 

&pchiFill); 

EnterCritical Section(&G1obalCritical Section); 

PutString(PRIME Xl+2, PRIME Y2-1, WHITE ON BLUE, "Ad", TestNumber, ""); 

unique handle - handles + 10 * handle mod++; 

WriteConsoleOutputAttributelhStdOut, Local, C N LENGTH, 

strcpy(GCompName[handles], CompName); 

ComputPrimeCoord, idummy) ; 

mxyputc(2, 21, (char)32, 75, CYAN ON CYAN); 

mxyputs((UCHAR)(PRIME X2-7), (UCHAR)PRIME Y2-1, LocalCompName, 

PutString(27, 21, RED ON CYAN, "Computer %s", CompName, ""); 

WHITE ON BLUE); 

PutString{54, 21, RED ON CYAN, "(%1d)", unique handle, "“); 

NoPrimestPrimeSHandle] ++; 

Sleep(2 * WAIT DISPLAY); 

LeaveCri ti cal Section(&G1obalCriticalSection) ; 

mxyputc(2, 21, (char)32, 75, CYAN ON CYAN); 

return PRIME; 

G1obalComputerHandleBuffer[handles] - unique handle; 

•pphContext - (PCONTEXT HANDLE TYPE)unique handle; 

) 

NoPrimes[handles] ■ 0; 

void TerminatePServer(handle t hi, ULONG PrimeSHandle) { 

handlesp - ++handles; 

UCHAR loop, loopshift; 

LeaveCri tical Section(&G1obalCriticalSection) ; 

char Buffer[256+STRING LENGTH]; 

return unique handle; 

EnterCriticalSecti on(&G1 obal Critical Secti on); 

) 

for(loop = 0; loop < (UCHAR)handles; loop++) { 

if(GlobalComputerHandleBuffer[loop] == PrimeSHandle) { 

UCHAR RemotelsPrime(handle t hi, ULONG PrimeSHandle, ULONG TestNumber) { 

mxyputc(2, 21, (char)32, 75, CYAN ON CYAN); 

ULONG count, HalfNumber * TestNumber / 2 + 1; 

PutString(27, 21, RED ON CYAN, "Computer %s Exited!", 

SMALL RECT pRectTest - { TEST Xl+1, TEST Yl+2, TEST X2-1, TEST Y2-1 }; 

GCompName[1oop], ""); 

SMALL RECT pRectPrime = { PRIME Xl+1, PRIME Yl+2,PRIME X2-1, PRIME Y2-1 ); 

mxyputc(59, (UCHAR)(4+1oop), (char)32, 15, CYAN ON CYAN); 

COORD coordTest - f TEST Xl+1, TEST Yl+1 ); 

SIeep(WAIT DISPLAY); 

C00R0 coordPrime - { PRIME Xl+1, PRIME Yl+1 ); 

mxyputc{2, 21, (char)32, 75, CYAN ON CYAN); 

CHAR INFO pchIFill - { (char)32, WHITE ON BLUE ); 

break; 

COORD ComputTestCoord - { TEST X2-7, TEST Y2-1 }; 

i 

COORD ComputPrimeCoord = ) PRIME X2-7, PRIME Y2-1 ); 

) 

DWORD dummy; 

if(1oop < handles-1) ( 

WORD Local[C N LENGTH); 

loopshift - loop; 

char Buffer[STRING LENGTH], LocalCompName[STRING LENGTH]; 

for(loop - loopshift; loop < (UCHAR)(handles-1); loop++) { 

unsigned loop; 

strcpy(GCompName[loop], GCompName[loop+1]); 

EnterCriticalSection(&G1obalCritical Section); 

G1obalComputerHandleBuffer[1oop] - 

for(loop - 0; loop < handles; loop++) 

G1obalComputerHandleBuffer[1oop+1]; 

if(GlobalComputerHandleBuffer[loop] -- PrimeSHandle) { 

NoPrimes[loop] - NoPrimes[1oop+1]; 

strcpy(LocalCompName, GCompName[loop]); 

} 

PrimeSHandle » loop; 

) 

break; 

handles--; 

) 

LeaveCriticalSection(&G1obalGritical Sect1 on); 

LeaveCritical Section(&G1obalCritical Section); 
for(loop - 0; loop < C N LENGTH; loop++) 

i 

Local[loop] = WHITE ON BLUE; 

void PCONTEXT HANDLE TYPE rundown(PCONTEXT HANDLE TYPE phContext) { 

if(VK ESCAPE — get character(NO WAIT)) { 

handle t dummy; 

EnterCriticalSection(&G1obal Critical Section); 

if(handlesp ■■ handles) { 

Sleep(WAIT); 

mxyputs(27, 2, "Rundown Executed", RED ON CYAN); 

clearscreen(O); 

TerminatePServer(dummmy, (ULONG)phContext); 

exit(SUCCESS EXIT); 

Sleep(WAIT DISPLAY); 

LeaveCri ti cal Secti on (&G1 obal Cri ti cal Secti on); 

mxyputs(27, 2, * ", CYAN ON CYAN); 

DeleteCriticalSection(&G1 obal Cri ti cal Section); 

) 

i 

handlesp ■ handles; 

EnterCriticalSection(&G1 obal Cri ti cal Section); 

ScrollConsoleScreenBuffer(hStdOut, ApRectTest, NULL, coordTest, 

) 

&pchiFill); 

PutString(TEST_Xl+2, TEST_Y2-1, WHITE_ON_BLUE, M %d\ TestNumber, ""); 

/* End of File */ 
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know the address of the remote procedure it wants to call. 
The binding is the means by which the client has the server 
call the correct remote procedure on its behalf. There are two 
types of binding available to RPC applications: manual and 
automatic. Manual binding is the typical choice, although it 
requires more programming effort. When using automatic 
binding the MIDL compiler generates all the code necessary to 
create and maintain the binding. This makes the 
programmer’s job much easier at the cost of less control. Use 
of automatic binding is usually restricted to very general ap¬ 
plications that do not care which server they bind to. For ex¬ 
ample, an application that wants to get the time from a 
remote server is a good candidate for automatic binding. 


Listing 6 prime.idl — Interface definition language 
file for distributed application 


[ uuid (62387AFE-C34B-1ABE-B235-98765233AFEA), 
version(1.0), 
pointer_default(unique)] 
interface prime 
{ 

typedef [context_handle] void *PCONTEXT_HANDLE_TYPE; 

typedef [ref] PCONTEXT_HANDLE_TYPE *PPCONTEXT_HANDLE_TYPE; 

char RemoteIsPrime([in] handle_t hi, [in] unsigned long PrimeSHandle, 

[in] unsigned long TestNumber); 
unsigned long InitPServer([in] handle_t hi, 

[out] PPCONTEXT_HANDLE_TYPE pphContext, 

[in, string] unsigned char *CompName); 
void TerminatePServer([in] handle_t hi, [in] unsigned long PrimeSHandle); 
} 


Listing 7 prime, mak — Makefile for prime number 
application 


!include <NTWIN32.MAK> 
cflags = $(cflags:G3=Gz) 

•c.obj: 

$(cc) $(cflags) $(cvarsmt) $< 
all : client server 
client : client.exe 

client.exe : client.obj prime_c.obj directio.obj 
$(1 ink) $(conflags) -out:client.exe \ 
client.obj prime_c.obj directio.obj \ 
rpcrt4.1ib rpcndr.lib rpcns4.1ib $(conlibsmt) 

client.obj : client.c prime.h 

directio.obj : directio.c directio.h 
$(cc) $(cflags) $(cvarsmt) directio.c 

prime_c.obj : prime_c.c prime.h 

$(cc) $(cflags) $(cvarsmt) prime_c.c 

server : server.exe 

server.exe : server.obj remote.obj prime_s.obj directio.obj 
$(1ink) $(conflags) -out:server.exe \ 
server.obj prime_s.obj remote.obj directio.obj \ 
rpcrt4.1ib rpcndr.lib rpcns4.1ib S(conlibsmt) 

server.obj : server.c prime.h 

remote.obj : remote.c prime.h 

prime_s.obj : prime_s.c prime.h 

$(cc) $(cflags) $(cvarsmt) prime_s.c 

prime.h prime_c.c prime_s.c : prime.idl 

midi -cpp_cmd $(cc) -cpp_opt "-E" prime.idl 


You can view binding to a remote server as a process 
similar to opening a file. When you open a file, you do so 
symbolically with a filename —your program is insulated from 
having to know precisely where and on what disk the file 
resides. If the file exists and the open succeeds, you get a file 
handle that you have to pass to the file I/O functions. The file 
handle lets the file I/O package maintain information about 
the state of the file, so that your program is insulated from its 
physical details. Likewise, when you bind to a remote server, 
you don't have to specify details such as network addresses. If 
the desired server exists and the binding succeeds, you get a 
handle that you will use to perform remote procedure calls to 
that server. 

Binding Handles 

An RPC application has to deal with two types of handles: 
binding handles and context handles. Binding handles contain 
information about the binding between the client and the 
server, while context handles maintain state information. 

A client initiates the binding process by calling several RPC 
run-time functions. If everything goes smoothly (a valid server 
is found), then the client receives a binding handle. A binding 
handle is an opaque data structure that the client must use 
when making remote procedure calls to that server. The bind¬ 
ing handle is always the first parameter passed to a remote 
procedure. There are two methods of passing binding handles 
in an RPC application: implicit and explicit. 

Implicit handles are easier to use than explicit handles, as 
the code to pass the handle is generated by the MIDL com¬ 
piler. when using implicit handles, the binding handle is 
declared as a global variable so that the C code generated by 
the MIDL compiler can package it for transmission to the 
remote procedure's stub. All binding handles are eventually 
converted to explicit handles, the only difference is whether 
you write the code to pass the explicit handle or whether you 
let the MIDL compiler generate the code to pass it. If you use 
explicit handles, you have to pass the handle to each RPC call 
yourself, but you can manage simultaneous connections to 
multiple servers. The RPC application presented in this article 
uses explicit handles. 

RPC Versus Normal Calls 

A remote procedure call looks like a normal procedure call 
to the client, but there are differences you should be aware 
of. Since the client and the server are two different executable 
programs, you cannot use global variables to communicate. 
Another difference is in the performance of pointer 
parameters. With a simple function call, passing a pointer (to a 
string, for example) can be much more efficient than passing 
the entire string itself. With a remote procedure call, however, 
the MIDL compiler has to generate code to copy the entire 
string anyway; just passing a pointer would be of no use to a 
server that resides on a separate machine. The Interface 
Definition Language gives you some options in dealing with 
pointer parameters. You can group the pointers transmitted to 
remote procedures into three basic categories: reference 
pointers, unique pointers, and full pointers. 

Reference pointers are the most efficient of all, but allow 
you less power in manipulating the pointer. A reference 
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pointer points to valid data, and does not change its value. It 
is basically like a constant pointer to a specific address in 
memory. In addition, a reference is not allowed to cause alias¬ 
ing. This means that a reference pointer is the only way to 
access the block of memory it is pointing to. Using a reference 
pointer, you allow the compiler to do significant optimizations 
on the data transfer and pointer emulation mechanism. 

Unique pointers are less efficient than reference pointers, 
but allow you more flexibility. A unique pointer can be NULL, 
and can change the memory address it is pointing to on the 
fly. A unique pointer cannot be aliased. 

A full pointer is the least efficient of the three pointer 
types, but it allows you the most flexibility with what your 
pointer can do. A full pointer can be 
NULL and change the memory address 
it is pointing to. Also, a full pointer can 
be aliased. Using this method does not 
allow the compiler to make any as¬ 
sumptions about the pointer or about 
memory referenced by this pointer. The 
memory can be accessed at any time 
and by any pointer. Full pointers are 
most useful for distributing existing 
code with RPC. This way, you can get 
your application up and running in the 
shortest time possible, and then later 
go back and improve it. Unfortunately, 
full pointers are not supported by 
Microsoft RPC vl.O. 

Complex structures pose more 
problems. Consider what happens if you 
attempt to pass a pointer to a doubly- 
linked list as a parameter to a remote 
procedure. In such cases the code 
generated by the MIDL compiler is in¬ 
sufficient as it cannot know the exact 
structure of your linked list. Microsoft 
RPC provides the solution to this prob¬ 
lem in the form of user-defined mar¬ 
shalling (packetizing) and unmarshalling 
routines. In these cases, you have to 
supply special callback functions, ex¬ 
ecuted by the client and server stubs, 
that transfer all or part of the special 
memory structure into a standard array 
that MIDL can transmit to the server. On 
the server, the unmarshalling routine is 
called, to convert the array back into 
the structure expected by the remote 
procedure. 

An RPC Example 

The RPC application provided in this 
article computes prime numbers, using 
most of the RPC features I've described. 

Prime numbers provide a simple ex¬ 
ample of a computationally intensive 
task that can benefit from distributed 
computing. To keep the code brief, this 
example uses the Win32 console func¬ 


tions to create a text-mode Windows NT application. The con¬ 
sole functions in this example are handled by two source files, 
directio.c (Listing 1) and directio.h (Listing 2). 

I designed the client side of the prime number application 
so that it can operate whether or not the server side is avail¬ 
able. When executed, it creates a thread for each server. Each 
thread then attempts to bind to its designated server, then 
the client sends work to all servers with which it bound suc¬ 
cessfully. Each thread that was unable to bind to a server 
waits a predetermined period of time before trying to rebind. 
In addition, the client creates one local thread that computes 
prime numbers on the client's computer. The source code for 
the prime number client is in client.c (Listing 3). 
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The client searches for prime numbers using a divide and 
conquer algorithm. Each thread takes a number and tests it to 
see if it is prime. To ensure that work is not replicated be¬ 
tween the threads, the client keeps one global variable, Next- 
Number, that contains the value of the next number to be 
tested. Each thread increments this number within a critical 
section to ensure that no other thread is accessing it simul¬ 
taneously. Once the increment is complete, the thread copies 
it to a local variable, temp, and exits the critical section, temp 
can then be used safely because since it is local to the thread 
no other thread can modify it. Another thread can then access 
the already incremented value of NextNumber. This ensures 
that no two threads will compute the same number. The 
client has several runtime options. Type “client /?” for a list of 
these features. You can execute the client by typing: 

CLIENT -N \\FIRST_SERVER_NAME;\\SECOND_SERVER_NAME;... 

Client Initialization 

After parsing the command-line arguments, the client uses 
the RpcStringBindingCompose () function to create a string 
binding for each server it intends to bind with: 


RpcStringBindingCompose () is a convenience function that 
combines all the pieces of a string binding together and 
returns the combined string in a character array allocated by 
the function. This memory is later freed by calling RpcString- 
Free(). 

A string binding is a string of characters that defines all the 
attributes for the binding between the client and the server. A 
string binding consists of the UUID, protocol sequence, net¬ 
work address, end point, and options. All the parameters used 
to create the string binding can be modified by the user 
through the use of command-line arguments. 

The UUID specifies an optional number used for identifica¬ 
tion purposes. This UUID allows clients and servers to distin¬ 
guish different objects from one another. In this example the 
field is set to NULL by default. 

The protocol sequence specifies the low-level network 
protocol to be used for the network communication. There 
are several network protocols currently supported. This ex¬ 
ample uses the named pipes (“ncacn_np") protocol native to 
Windows NT. Microsoft is planning to release a kit allowing 
developers to support other network protocols, but no date 
for this release has been given. The currently supported net¬ 
work protocols are as follows: 


status = RpcStringBindingCompose( 
pszUuid, pszProtocolSequence, 
pszNetworkAddress[i], pszEndpoint[i], 
pszOptions, &pszStringBinding[i]); 


Figure 1 
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The network address is the address of the server with 
which the client wishes to bind. When using the named pipes 
protocol sequence, the network address is described in the 
following form: “Wservemame", where “servername” is the 
name of the server computer. The type of valid network ad¬ 
dress depends on the protocol sequence used. Different 
protocol sequences have very different methods of defining 
network addresses. 

The end point used to create the binding specifies the net¬ 
work end point at which the server application is listening. 
The end point is like a street address to a particular server 
application, while the network address is like the city where 
your server lives. As is the case with the network address, the 
type of end point reflects the protocol sequence being used. 
When using the named pipes protocol sequence, the valid end 
point specifies the pipe that the server is listening to. A valid 
end point for the named pipes protocol sequence is as fol¬ 
lows: “\pipe\pipename", where pipename is an application- 
defined name for the pipe used for the low-level network 
communication, between the client and the server. 

The options parameter is a miscellaneous string to be used 
for whatever special settings are appropriate for a particular 
protocol sequence. For the named pipes protocol sequence, 
the only currently available option is "security=true”. This turns 
on security mechanisms for the remote procedure call. 
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RpcStringBindingCompose() combines the parts of a 
string binding together. The purpose of a string binding is to 
specify all the parameters for the protocol sequence (network 
protocol) used. The client then transforms each string binding 
into the actual binary binding with RpcBindingFromString- 
Binding(). 

status = RpcBindingFromStringBinding( 
pszStri ngBi ndi ng [i], &Bi ndi ngHandle[i]); 

The binding can then be thought of as a magic cookie or 
handle with which you can make remote procedure calls. 

The client calls CreateThreadf) to create a thread to 
manage each server. Each thread is passed a number desig¬ 
nating a server it is responsible for. In addition, the client ini¬ 
tializes a critical section object for use later, when accessing 
global variables from the threads. Lastly, the client calls Get- 
ComputerNameO so that it can pass the returned string to the 
server. The server displays this string so that the user can see 
which client is making remote procedure calls. 

Once the client has obtained a valid binding to each server, 
it attempts to initialize these servers on a logical level. To do 
so, it calls a special remote procedure available on each prime 
number server: InitializePrimeServer(). This function is 
designed to notify the server that a client is planning to make 
requests. InitializePrimeServer() accepts a binding handle, 
context handle, and the name of the computer retrieved by 
GetComputerName(). 

Client Computation 

After the client initialization is completed, prime number 
computation begins. thread_local() computes prime num¬ 
bers locally on the client computer via IsPrime(). 
thread_remote() makes a remote procedure call to deter¬ 
mine if a number is prime via RemotelsPrimef). In this case, 
because RemoteIsPrime() is a remote procedure call, it is em¬ 
bedded in an exception handler. 

If an exception occurs the client attempts to recognize the 
error and provide an error message on the console display. If 
the exception that occurred indicates that the server is off¬ 
line, then the client thread waits a specified period of time 
before attempting to rebind to that server. 

When the client terminates normally, via the Escape key, a 
special remote procedure call, TerminatePrimeServerf) , is 
made to notify the server of the client's plans to exit. The 
server can then take action to free memory and update its 
display to reflect the new status. 

The Server 

The prime number server has an important, if unrewarding, 
job. It must register its interface and begin to listen for client 
requests. The source code for the prime number server 
resides in server.c (Listing 4) and remote.c (Listing 5). 

RpcServerUseProtseqEpO notifies the RPC run-time 
module to register a protocol sequence, end point, and 
security attribute on which to accept remote procedure calls. 
This is the station the server listens to, to hear the client’s 
cries for help. RpcServerRegisterlfO registers the server's 
interface. It accepts the handle to the interface being 


registered and . two optional management parameters not 
used in this example. This interface is defined in the IDL file. 

The last RPC runtime function the prime number server 
calls begins listening for client requests. In this example, Rpc- 
ServerListen() never returns. Until a client makes a remote 
procedure call, the server cannot do anything. To avoid this 
problem, I create a special thread for the server to perform 
maintenance tasks even when not in use. This thread is 
created with the CREATE_SUSPENDED attribute so that it can be 
subsequently modified with the THREAD_PRIORITY_LOWEST at¬ 
tribute. This ensures that the maintenance thread consumes 
the least amount of CPU cycles possible when it is restarted 
with ResumeThread(). In this example the maintenance thread 
provides some prime number statistics and checks to see if 
the Escape key was pressed. 

The server also has a special context rundown routine that 
can be seen in remote.c (Listing 5). As you may recall, the 
client calls TerminatePrimeServer() when the user presses 
the Escape key. What happens if the client terminates abnor¬ 
mally? Perhaps the client crashed, the power went out, or the 
computer failed. In any case, the server must be fault tolerant 
and not allow such a possibility to impair its performance for 
other clients that may still be on-line. Whatever Terminate- 
PrimeServer() would have done, the server needs to do. The 
designers of RPC took this situation into account and came up 
with a special facility known as a rundown. This rundown is a 
user-defined function called automatically by the RPC runtime 
whenever the client terminates. If the client terminates nor¬ 
mally by calling TerminatePrimeServer() , the rundown 
routine is skipped. However, if the client terminates abnormally, 
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Table 1 

Range 

1 computer (sec.) 

4 computers (sec.) 

Ratio 

1 - 1,000 

35 

40 

0.88 

100,000 - 101,000 

40 

42 

0.95 

1,000,000 - 1,001,000 

100 

61 

1.64 

10,000,000 - 10,001,000 

581 

170 

3.42 


the rundown routine is called to perform the necessary clean¬ 
up. 

The prime number interface definition file specifies the RPC 
interface between the client and server. The prime interface is 
defined in prime, idl (Listing 6). The UUID, version number, 
and pointer type used are defined here for the interface 
header. Following that is the actual interface definition, con¬ 
sisting of the function prototypes with special IDL flags. 

Building the Example 

The makefile used to build the prime number application is 
available in prime.mak (Listing 7). This file handles the building 
of the entire example, including execution of the MIDL com¬ 
piler, C compiler, and linker. Figure 2 shows the overall build 
process. 

To build and run this example you need to have at least 
one computer capable of running Windows NT. This is possible 
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because both the client and the server 
can be run on one computer. If you 
wish to test this application across a 
network, you will need at least two 
computers running Windows NT, both 
with supported network cards. You 
must also have Windows NT and the 
Microsoft Win32 Preliminary SDK for 
Windows NT. 

Microsoft RPC vl.O provides support 
for MS-DOS and Windows for 
Workgroups. Applications on both of these platforms can 
make remote procedure calls to servers running Windows NT. 
MS-DOS and Windows applications cannot, however, become 
RPC servers as these platforms lack the multithreading 
capability required. 

Debugging distributed RPC applications is slightly different 
from debugging conventional applications because of the 
added factor of the network. For this reason it is best to 
separate the server initialization code from the remote proce¬ 
dures themselves. This is done in the Prime RPC application 
with server.c and remote.c. Both files are linked together to 
produce the server, but during the debugging stage this 
separation can be invaluable. By dividing the server into two 
parts, you permit yourself the option of linking the remote 
procedures directly with the client to produce one standard 
application. In this manner you can test the application as a 
whole without worrying about the network. Once your pro¬ 
gram works properly, you can divide it into a client and server 
to test it in a distributed environment. 

What advantage is there to computing prime numbers in a 
distributed manner across a network, compared to the con¬ 
ventional way on one computer? The prime example 
presented in this article provides some simple timer routines 
to let you know how long the computations are taking. Figure 
3 shows that when computations are relatively small (1- 
1000), then distributing an application can actually cause the 
performance to worsen. This is because the overhead of RPC is 
significant compared to the work done by the server. In addi¬ 
tion, these times were clocked with the March beta version of 
Windows NT. Perhaps the release version will have better per¬ 
formance. In any case, you can still observe that under some 
circumstances, much better performance can be achieved 
with RPC. Once the calculations required become very large 
(10,000,000 and up), the overhead of RPC becomes insig¬ 
nificant. When I clocked these times, the improvement with 
the distributed prime computations approached an order of 
3.5 times faster with four computers than with only one. A 
smart application might make remote procedure calls only 
when the possible gain outweighed the overhead. As net¬ 
works and operating systems that support distributed com¬ 
puting become more and more common, RPC becomes more 
likely to play a part in your next application. □ 
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ZylNDEX Developer’s Toolkit 


Bruce Graves 

The ZylNDEX Developer's Toolkit is a Windows 3.1 library 
(also available for DOS and UNIX) that provides very fast access 
to information stored in text files, word-processing documents, 
spreadsheets, and even dBase .DBF and .DBT files. To give you 
an idea of what “very fast access” really means, the Toolkit 
allows you to find every occurrence of a phrase like “Paul 
Revere” in tens or hundreds of megabytes of data in several 
seconds. 

To achieve performance like this, products like the Toolkit 
divide the search process into two parts. The first, indexing, 
makes the classic space-versus-time tradeoff. By scanning a 
set of files and building an index that points to every sig¬ 
nificant word in those files, the index engine does most of the 
hard work ahead of time. To actually perform a search, the 
search engine works with the sorted index files, not the 
original data files, and produces a list of all the locations 
where a particular expression occurs. 

ZylNDEX 

The Toolkit implements a subset of the features of 
ZylNDEX, a product that’s been available since 1984 for DOS 
and is now available for Windows. Experimenting with 
ZylNDEX was interesting because it gave me a feel for the 
power that a comprehensive indexing utility can provide. It 
also highlighted some of the Toolkit's weak spots and made 
me realize just how much work it would take to build a com¬ 
mercial application on top of the Toolkit. More on those topics 
shortly, after a quick look at ZylNDEX. 

ZylNDEX consists of two programs: ZyBUILD and ZyFIND. 
ZyBUILD is dedicated to creating, building, updating, optimizing, 
duplicating, and deleting indexes. It lets you specify a direc¬ 
tory where an index will be created and indicate which files 
will be included in it. The filenames can include wildcard sym¬ 
bols, and you can tell ZyBUILD to recursively include all the 
files in the subdirectories on a given path. For example, you 
might include all the .doc files under e:\wpdocs and all the 
. txt files under c; \mail. You can also tell ZyBUILD to exclude 
specific groups of files, such as the .doc files in 
d: \wpdocs\old. 

Once you've specified which files should be included in an 
index, ZyBUILD performs the actual indexing operation. If the 
index is new, ZyBUILD processes every file you’ve specified. If 


the index already exists, ZyBUILD checks the time and date 
stamps on each file and only processes those that have been 
modified since the last build. 

A set of “control files" determines how ZyBUILD creates in¬ 
dexes. One of the most important control files is the list of 
“noise words,” such as “an,” “the,” “her,” etc., that are so com¬ 
mon that they aren't worth indexing. You can tailor the noise 
list to suit your needs, but be careful — if you add too many 
common words, the indexing process can get really bogged 
down. The indexes themselves consist of a series of files, all 
stored in an index directory, that contain every non-noise 
word and its locations in individual documents. 

ZyBUILD maintains an “index set file” that’s supposed to 
contain the location of every index that ZyFIND and ZyBUILD 
can access. You're not allowed to move, copy, or delete index 
directories manually, such as from the DOS prompt. If you do, 
you'll invalidate the index set file, which can confuse ZyBUILD 
and ZyFIND. Once this happens, you have two options: re-in¬ 
stall and rebuild everything from scratch, or use an undocu¬ 
mented debugging switch to fix things up. 

ZyFIND 

ZyFIND allows you to search one or more indexes created 
by ZyBUILD for arbitrary expressions. The expressions are 
Boolean expressions with quite a few extensions. The gram¬ 
mar is too broad to explain completely, but a few examples 
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should give you an idea of its power and ease of use. The 
expression 

pike 

tells ZylNDEX to find all the files that contain the word "pike”, 
while 


Figure 1 ZylNDEX Toolkit Engines 
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pike AND pickerel 

indicates that you’re interested in all the files that contain 
both “pike” and "pickerel.” The AND is a reserved operator 
keyword, not a search target It’s also on the default noise list, 
so it isn’t usually present in the index anyhow. All ZyFIND 
searches are case-insensitive, so "pike”, "PIKE”, and "plkE” are 
considered equivalent 

You can use DOS-style wildcard characters in expressions, so 
pri* AND las?? 

will find all files that contain the words "pri,” “print,” "private,” 
etc., and words like "laser” or "lasso” (but not "las," "last,” or 
"lasers"). The search works on complete words, so there’s no 
way to include white space as part of the target string. 

It’s worth looking at two more sample expressions that 
demonstrate some of the high-level capabilities that are built 
into the ZylNDEX search expression grammar. The expression 

FNAME=tr* AND tree w/10 palm 


Listing 1 build.cpp - Sample code to build index 


u . 

// build.cpp 

// . 

#include <windows.h> 
linclude <string.h> 
linclude "zyhapi.h" 

int PASCAL WinMain(HINSTANCE, HINSTANCE, LPSTR, int) 

{ 

// The paths for the control files and the index, 
char *psControlPath ■ "d:\\zydev\\control"; 
char *psIndexPath - "d:\\mp\\zy\\index"; 

// Start the Toolkit. 

ToolkltOptions tkOptlons; 
memset(&tkOptions, 0, sizeof(tkOptions)); 
tkOptions.nResourceLevel ■ ZY_MEDIUM; 

ZYstart(psControlPath, 
tkOptions); 

// Delete any existing index, then create an empty one. 
ZYdeletelndex(psIndexPath); 

ZYmakelndex(psIndexPath); 

// Open the index in INDEX mode and get its handle, 
long lZYIndex; 

ZYopenIndex(psIndexPath, 

ZY INDEX, 

AlZYIndex); 

// 

// Add all the Microsoft Word docs in e:\wpdocs and 
// all its subdirectories to the index. Note that the 
// string parameter is one long string, not separate 
// ones. 

// 

ZYaddDocs(lZYIndex, // index handle 

ZYIWEDIATE, // script included here 

"5000\r\n" // required constant 

"*.bak\r\n \r\n" // exclude file types 

"e:\r\n" // drive 

"Wwpdocs R\r\n" // path and recursion flag 
"*.doc\r\n" // include file types 

"\r\n"); // end of script 

// Close the index and shut down the toolkit. 
ZYcloselndex(lZYIndex); 

ZYfin1sh(); 
return 0; 

} 

// End of File 
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says to search the index for all files with names starting with 
“tr” that contain the word “tree” within 10 words of the word 
“palm”. Finally, 

EOP to EOP {2 of {smart, flexible, cheap})} 

would retrieve all files that include a paragraph that contains 
two of the words "smart,” “flexible,” and “cheap” (EOP stands 
for end-of-paragraph). 

Hits 

When ZyFIND completes a search on one or more indexes, 
a Search Results window lists all the files that contain one or 
more instances of the expression you specified, also known as 
“hits.” By convention, hits don't necessarily correspond to the 
number of occurences of a specific expression. For example, if 
you search for “foo AND bar,” and the words “foo” and “bar” 
each appear exactly once in a file, ZyFIND will report two hits, 
not one. 

When you select a specific file in the Search Results win¬ 
dow and hit Return, ZyFIND creates a File Display window that 
allows you to view the file in a basic text format. This can be 
really handy if you’ve indexed files from, say, four different 
word processors and a dBase file. You can move from hit to 
hit in the file with simple keystrokes, and if you issue the 
Launch command, ZyFIND will execute the application that 
Windows associates with the current file’s extension (for ex¬ 
ample, the Notepad editor with . txt files). 

The ZylNDEX interface is functional, though fairly primitive 
compared to many Windows applications. The dialogs are very 
basic, and the online help isn’t complete — for example, 
there’s no entry for "Index” — so keep the the manual close 
by. Overall, however, the ZylNDEX application is very powerful. 
If you've got to keep track of tens, hundreds, or even 
thousands of documents, it's like having a really fast research 
assistant at your fingertips. 

Numbers 

But how large are the index files that ZyBUILD and the 
Toolkit create? According to the ZylNDEX documentation, when 
the original data size is between 10 and 50 megabytes, 40 
percent of that size is a good estimate. For larger data files 
(over 300 megabytes), the index size usually drops to some¬ 
where around 25 percent of the data size. 

And how long does it take to build an index? On a 486- 
66DX2 with 16Mb of RAM, running Windows 3.1 with the 
SmartDrive cache set at 2Mb, ZyBUILD built an index for 7.4MB 
of data files in 15 minutes. The index files totaled about 
2.5Mb, or 33 percent of the original data size. The data con¬ 
sisted of four text files that I copied from the Microsoft 
Developer’s CD-ROM onto my hard drive; indexing them direct¬ 
ly from the CD took 51 minutes. 

Once the index exists, searching is very fast, even on 
moderately complicated expressions. I asked for all the occur¬ 
rences of the word “windows" and got results (a list of the 
four files and the number of hits in each) in under two 
seconds. It took about the same amount of time to find all 
occurrences of the expression “window w/10 (minimize OR maxi¬ 
mize)", which asks for all occurrences of the word “window” 


Listing 2 search.cpp - Using HAPI search 
functions 


// . 

// search.cpp 

// . 

linclude <windows.h> 

#1nc1ude <string.h> 
linclude <fstream.h> 
linclude "zyhapi.h" 

// 

// Open the given file, get the filename, and send info 
// to the output text file. Called by WinMain(), below. 

// 

void ProcessDoc(long lZYIndex, int nFileld, ofstream &ofs) 

{ 

// Open the given file. 

ZYopenDoc(lZYIndex, nFileld); 

// Get the number of hits, filename, and path, 
char sInfo[HAPI_INF0_LENGTH+l]; 

ZYgetResult(lZYlndex, // index handle 

nFileld, // file id 

FILENAME | PATHNAME, // info requested 

slnfo, // put info here 

sizeof(slnfo)); // max info chars 

ofs « "Doc I" « nFileld « " " « slnfo « endl; 

// The current line number (first line in file «■ 0). 
long 1 Line - (-1); 

// 

// Seek to each line containing a hit, get the line I, 
// and write it to the output stream. 

// 

while(l) { 

long IResultLine; 
int nResult - 

ZYseekDoc(lZYIndex, // index handle 

nFileld, // file id 

ZY_SEEK_F0RWARD, // find next hit 
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Listing 2 continued 


lUne, // current line 

MResultLine); // resulting line 

lUne - IResultLine; 

if(nResult 1- 0) 
break; 

ofs « " line #" « ILine « endl; 

} 

// Close the file. 

ZYcloseDoc(lZYIndex, nFileld); 


int PASCAL WinMain(HINSTANCE, HINSTANCE, LPSTR psCmd, int) 
{ 

// The paths for the control files and the index, 
char *psControlPath - "drWzydevWcontrol"; 
char *psIndexPath « "diWmpWzyWindex"; 

// Start the Toolkit. 

ToolkitOptions tkOptions; 
memset(&tkOptions, 0, sizeof(tkOptions)); 
tkOptions.nResourceLevel ■ ZY_MEDIUM; 

ZYstart(psControlPath, 
tkOptions); 

// Open the index In SEARCH mode and get its handle, 
long lZYIndex; 

ZYopenIndex(psIndexPath, // path to index 

ZY_SEARCH, // search mode 

ilZYIndex); // put handle here 

II 

// Execute a search for the expression passed to 
// WinMainQ on the command line. 

II 

int nFiles; 
long lHIts; 

ZYsearchIndex(lZYIndex, // index handle 

psCmd, II search request 


within 10 words of "minimize” or "maximize.” Finding all the 
paragraphs that contained two of the words "pen,” "brush,” 
and "region” took roughly nine seconds. 

Back to the Toolkit 

As I mentioned earlier, the Toolkit implements a subset of 
the ZylNDEX capabilities. It contains 19 individual functions, 
referred to as the "High-level Application Programming Inter¬ 
face,” or HAPI. These functions reside in one main DLL, 
hapi.dll, and three auxiliary DLLs, zynovell.dll, 
zybanyon.dll, and zyddd.dll. The first two auxiliary DLLs are 
required to detect and interact with networks, while the third 
provides stubs for potential library extensions. The Toolkit's 
function is illustrated in Figure 1. 

The HAPI contains functions to initialize and shut down the 
Toolkit, as well as create, delete, open, and close indexes. 
Once an index has been opened, there are functions to add 
and remove individual documents and to optimize the index 
after multiple changes have been made. These functions cor¬ 
respond to the operations performed by ZyBUILD. 

The remaining functions implement a subset of the ZyFIND 
operations. The most important one is probably ZYsearch- 
Index(), which takes a search request expression (in the 
same high-level format as you would use in ZyFIND) and 
returns a list of the index files that contain hits. Additional 
functions let you gather information about these files, then 
extract their ASCII text in line-delimited chunks. The Toolkit 
takes care of filtering out formatting information and the 
other “extras” that most word-processing documents contain. 




★ 

★ 


Windows Sockets, 
RPC/XDR, 
Telnet, FTP... 


for Windows 


O 


Windows Sockets, Berkeley Sockets 
Kernel, RPC/XDR, FTP and Telnet 
toolkits ... all in one 
100% DLL (uses only 4K DOS memory) 
Uses less memory than any other DLL or 
TSR implementation even when loaded 

Up to 128 concurrent sockets 
Coexists with Novell, Banyan or LAN 
Manager at no additional cost 
Supports NDIS, ODI and Packet drivers; 
SLIP and PPP with scripting 
TCP Tools: FTP (drag and drop), TFTP, 
Telnet, LPR/LPD, Back-Up with TAR 


fastfacts: 408.867.4742 
fax: 408.741.0795 

email: mktg@distinct.com 


dfstmct 

408.741.0781 


□ Request 336 on Reader Service Card □ 
Page 46 — Windows/DOS Developer’s Journal 


buiId.cpp 

build.cpp (Listing 1) is a simple Windows program (so 
simple, in fact, that it never even creates a window!) that 
builds an index. It begins with a series of straightforward HAPI 
calls to start the Toolkit, then create a new, empty index. The 
location of the index and the control files (such as the noise 
word list) are determined by the psControlPath and ps- 
IndexPath variables. 

The next step is to actually open the index in ZY_INDEX 
mode (as opposed to ZY_SEARCH mode) and get the equivalent 
of a handle to it, which is stored in the lZYIndex variable. The 
call to ZYaddDocs() does all the real work in this program; its 
string parameter, whose grammar is described in the Toolkit 
documentation, tells the Toolkit which files to add to the 
index. In this case, all the .doc files in the d: \wpdocs directory 
and all of its subdirectories will be added. 

Though the call to ZYoddDocs() returns fairly quickly, the 
real work can take a while to execute. This program doesn't 
take advantage of it, but the background process executed by 
the Toolkit sends a periodic status message to all popup win¬ 
dows. You can use this message to display a status indicator, 
such as the percent of the indexing that has been completed, 
the way that ZyBUILD does. The last HAPI calls in the program 
simply close the index and shut down the Toolkit. Once the 
build process is complete, the index is ready for use - by your 
own custom program, or by the ZyFIND program. 
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search.cpp 

search.cpp (Listing 2) is another simple Windows program 
that demonstrates some of the HAPI search functions. It takes 
a ZylNDEX search expression on its command line, opens the 
index that was created by build.cpp, and writes the names 
of the files and the line numbers in which the search expres¬ 
sion occurs to the file out.txt. 

The only really interesting HAPI functions that search.cpp 
uses are ZYsearchlndexf), which actually does the search, 
and ZYseekDocQ. The seek function is used to walk a "cursor” 
through each of the files where hits occurred. This program is 
interested only in the line numbers, but more advanced ap¬ 
plications (such as ZyFIND) can actually read the text from 
those lines (or any other lines) and do something interesting 
with it, such as displaying it in a window. Note that the HAPI 
functions take care of filtering out all the word-processor- 
specific formatting information; they provide your application 
with standard ASCII text Figure 2 is a sample of the output 
produced by search.cpp. 

The build.cpp and search.cpp programs are very short, 
but they demonstrate the power that the Toolkit delivers. 
They also demonstrate that the HAPI is fairly low-level in 
some respects. For example, you have to decipher the fairly 
complex grammar for the ZYaddDocs() function carefully: a 
mistake can be tough to track down — especially since you 
are unable to step into the library’s source code. A set of 
high-level C++ classes, like those that Borland includes on top 
of their Paradox Database Engine API, would be really helpful. 


Other Enhancements 

While the ZylNDEX documentation is excellent, the Toolkit 
manual needs some work. The descriptions for each of the 
HAPI functions are very short and sometimes ambiguous. For 
example, the ZYseekDocf) entry describes how to move from 
one hit to another and how to position the cursor at an ar¬ 
bitrary line in the file, but it doesn't explicitly tell you how to 
find the very first hit in a file or how to know when you've 
found the last one. 

In another case, the ZYgetResult() entry indicates that 
you have to allocate a buffer to receive file information, but 
fails to mention its minimum size. I discovered this omission 


Listing 2 continued 


&nFiles, // put # files here 

&lHits); // put # hits here 

// 

// Create the file for text output and process each 
// file that contained a hit. 

// 

ofstream ofs("words.txt H ); 

ofs « "Results for \""« psCmd « "\" « endl; 

for(int nFileld-O; nFileId<nFiles; nFileId++) 
ProcessDoc(lZYIndex, nFileld, ofs); 

// Close the index and shut down the toolkit. 
ZYcloselndex(lZYIndex); 

ZYfinish(); 
return 0; 

} 

// End of File 
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Figure 2 Sample output from search.cpp 


Results for "word" : 


#0 4 

PBXY.DOC 

E:\WPD0CS\MISC\ 

1 ine 

#36 


line 

#42 


line #48 


line 

#87 


#1 1 

ERIN.DOC 

E:\WPD0CS\MISC\ 

line 

#0 


#2 2 

VIRG.DOC 

E:\WPDOCS\MISC\ 

1 ine 

#0 


line 

#54 



by looking up an error code that 1 received in the zyhapi.h 
header file, which indicated that the buffer I was using was 
too small. Several other omissions left me unsure about some 
issues, such as exactly when it's safe to shut down the engine 
and whether multiple programs can utilize the engine at the 
same time. The handful of spelling and typographical errors 
that 1 encountered reenforced the impression that the manual 
was put together very quickly. 

One disappointment was that the examples included on 
the Toolkit disk demonstrated only a few of the 19 HAPI func¬ 
tions, and didn’t include some of the most critical ones, such 
as ZYsearchIndex(). The technical support at ZyLAB, available 
via phone or email, was excellent, but I'd rather be able to 
find answers in a product’s manual. [Editor's note: jZt/LAB notes 
that the most recent versions of the product do include ex¬ 
amples for all 19 functions.] 


Summary 

The ZylNDEX Developer’s Toolkit is a great set of routines — 
as far as it goes. Its ability to build indexes on a wide variety 
of file types, search the indexes very quickly for high-level 
expressions, and do all the work required to retrieve basic 
ASCII text from the indexed files is impressive. 

I had hoped to see all the ZylNDEX functionality provided in 
the Toolkit; as explained earlier, this isn't the case. I was look¬ 
ing for a comprehensive, step-by-step tutorial that would 
demonstrate how to use every existing HAPI function, but that 
was missing, too. Youshould also be aware that additional 
fees based on a sliding rate scale are required to include the 
Toolkit DLLs with your product. 

The ZylNDEX programs are robust and full-featured, while 
the Toolkit exhibits some typical early-version rough spots. If 
you're developing a high-priced commercial application or an 
in-house program and you need the Toolkit’s abilities now, 
take it for a spin. It comes with a 30-day money-back guaran¬ 
tee, which should provide plenty of time to put the HAPI 
through its paces. □ 
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■ Shareware Spotlight 


breads For Windows 


Victor Volkmari 


Introduction 

Threads For Windows, by Eschalon Development Inc. (New 
Westminster, B.C.), lets you create multithreaded applications 
in standard Windows 3.1. For example, you can create applica¬ 
tions that use background printing, complex redrawing, 
repagination, serial port polling, text searches, and more. With 
a properly threaded application you can improve performance 
without having to migrate to Windows NT or OS/2. Threads For 
Windows simplifies writing background processes for Windows 
applications. 

EDI's Threads For Windows (hereafter referred to as EDI 
Threads) provides a DLL-based interface. This works directly 
with Microsoft C/C++ (6.0 or later), Borland Turbo C/C++ (3.0 or 
later), and Borland Turbo Pascal for Windows. Other language 
products that can load dynamic link libraries may also work 
too. thrdutls.dll contains almost two dozen entry points 
(see Figure 1) yet remains smaller than 14Kb. 

EDI Threads provides multithreading functionality similar to 
that provided by comparable DOS-based alternatives such as 
Conquerrent C from Interstitial Software Systems (Garland, TX) 
and CTask from Thomas Wagner (Berlin, Germany) (see the 
bibliography at the end of this article for details on these 
products). Unlike these packages, EDI Threads does not have 
built-in intertask communication via semaphores, pipes, mail¬ 
boxes, or other mechanisms; instead, you must use traditional 
Windows intertask communication mechanisms. For example, 
you might use DDE sessions or DLLs that managed shared 
memory (GMEM_SHARE) allocated blocks (see Kerber (1990) for 
ideas on implementing client/server communications via 
shared memory DLLs). 

Interthread communication must always protect “critical 
sections” of code. A critical section is a fragment of code that 
accesses global resources and assumes that those global 
resources will not be modified by other tasks. If the critical 
section were interrupted, the resources might be modified by 
a competing thread, producing bugs. The critical section prob¬ 
lem occurs in all multitasking operating systems. 

In EDI Threads, almost any function can be turned into a 
thread. A threaded function can still call any Windows or run¬ 


time library function. Once you start a thread, control returns 
immediately to the code that called it, so your application 
continues uninterrupted from the user's point of view. Your 
application can start an unlimited number of threads concur¬ 
rently. 

EDI Threads is not a pre-emptive package — individual 
threads must yield control cooperatively, just as Windows 
processes do. Elowever, the package includes a scheduler that 
automatically decides what thread to run next when the cur¬ 
rent thread yields control. You can terminate or pause any 
thread at any time. In the remainder of the article, I will dis¬ 
cuss how applications can take advantage of all these features 
via EDI Threads' high-level and low-level APIs. 

High-Level API 

The high-level API provides the easiest means of getting 
your application up and running in the EDI Threads environ¬ 
ment. By contrast, the low-level API offers more opportunities 
for efficiency and control. In the simplest case, you only need 
to call two high-level functions: StartThread() and EndTask- 
Theods(). 

StartThread() simultaneously defines and launches a 
function as a new thread. For example, 

hThisThread = StartThread(MyProc, 2000, hWnd, wParam, 

1 Param); 

starts a new thread with a 2000-byte stack executing the 
function referenced by MyProc. MyProc could either be a 
thunk returned by MakeProcInstance() or, if you are using 
smart callbacks, just the name of an exported function. You 
can use hWnd, wParam, and IParam to pass arbitrary informa¬ 
tion to your thread function-, you can set them to zero if your 
thread function does not need them. If you launch several 
threads of the same function simultaneously, you could serial¬ 
ize them with IParam, for example. StartThread() returns a 
“thread handle," which is required by other functions in the 
EDI Threads API. Since EDI Threads does not support named 
threads, it is important to retain this handle. 


Victor R. Volkman received a BS in Computer Science from Michigan Technological University. He has been a contributing editor for 
windows/DOS Developer's journal since 1990. He is currently employed as Senior Analyst at H.C.I.A in Ann Arbor, Michigan. He can 
be reached by dial-in at the HAL 9000 BBS (313) 663-4173 or by Usenet mail to sysop@hal9k.com . 
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EndTaskThreads() immediately terminates all threads and 
frees the resources used to create them. This function re¬ 
quires the Windows task handle, which you can obtain by 
calling the Windows function GetCurrentTaskf). Of course, 
EndTaskThreads() will not automatically free other Windows 
resources allocated by the threads. To properly free up Win¬ 
dows resources allocated by independent threads, you could 
either use global variables to communicate with the main ap¬ 
plication or have the threads use some notification protocol 
for performing cleanup, much as Windows window procedures 
typically respond to a UM_DESTROY message by freeing up allo¬ 
cated resources. I will look at thread termination notification 
in detail later on. 

The high-level API lets you terminate threads more selec¬ 
tively, with EndThread(). EndThread() terminates only the 
thread you specify in the parameter list. EndTaskThreadsf) 
actually calls EndThread() once for each thread that the 
scheduler knows about. 

In other circumstances, you may only want to suspend the 
execution of a thread (to wait until a needed resource be¬ 
comes available, for example). RemoveThread() removes a 
thread from the scheduler’s run queue. The thread remains 
suspended until you terminate it by calling EndThread() or 
resume its execution by calling the low-level function Exec- 
Thread (). 

The low-level API function CreateThread() (discussed later) 
allows you to create threads that execute only when manual¬ 
ly started by ExecThread() rather than through the scheduler. 
The high-level API function AddThreadf) moves such a thread 
into the scheduler’s run queue. Similarly, when you want all 
threads to be manually started, you can bypass the scheduler 
by invoking ExecTaskThreads (). You can discover the total 
number of threads in the run queue by calling GetNum- 
Threads (). 

Last, you can set the standard thread execution time-slice 
length with SetThrdUtlsTimeSlice(). Although the time slice 
is specified in milliseconds, the actual resolution probably cor¬ 
responds to the system timer tick resolution (55 milliseconds). 
The time slice is the minimum amount of time that must 
elapse before a thread is rescheduled. 

The Low-Level API 

As I mentioned earlier, CreateThread() creates a thread 
that does not start executing automatically, but must be 


started manually. For example, you might want to start a 
background printing thread when your program starts up, but 
not run it until your application actually has something for it 
to do. You can restart it manually each time with Exec- 
Thread() or add it to the scheduler’s run queue with Add- 
Thread (). 


Product Information 


EDI Threads for Windows vl.O 

Eschalo n Development Inc. 

110-2 Renaissance Square 
New Westminster, BC 
V3M 6K3 Canada 
(604) 520-1543 
CompuServe: [76625,1320] 


Requires: Windows 3.1 and a language that can access 
DLL functions (e.g. C, Visual Basic, Pascal). 

Price: Evaluation is free, registration costs $99.95; source 
code is an additional $395. 

Availability: You can obtain this product from the HAL 
9000 BBS at (313)663-4173 or 663-3959 in file "wthrds.zip’’ 
or by anonymous FTP: 

ftp ftp.cica.indiana.edu 
cd /pub/pc/win3/programr 
get wthrds.zip 

Summary: EDI Threads for Windows provides a thread 
package for Windows applications. The package includes a 
scheduler and no limit on the number of threads or on 
what Windows functions an individual thread can call. 
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You can use EndThread() only on threads that are 
scheduled automatically. For manually activated threads, you 
must instead call the low-level TerminateThread(), followed 
by DisposeThread(). EDI Threads implicitly assumes that each 
thread intended to execute for long durations will follow a 
certain model: 

void far pascal MyFunc(PThreadRec *pThread, HWND hWnd, 
WORD wParam, LONG IParam) 


/* initialization code goes here 
while (YieldThread() ! = TM_QUIT) 
/* Thread processing loop */ 
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SOFTWARE FASTER 


French, German, Spanish, Italian, Japanese 
and many more languages... 
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Management tool 
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Dramatically reduce translation time 
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/* cleanup code goes here */ 
ExitThread(); 


Each call to YieldThreadf) will return either TM_CONTINUE or 
TM_QUIT. If TerminateThread() has been called since the last 
YieldThread(), then YieldThreadf) will return TM_QUIT. This 
implies that the thread should clean up and shut itself down 
as quickly as possible. Although there is no definite time limit 
for cleanup, the thread must not deny the TM_QUIT request. 
The TM_QUIT message processing in EDI Threads is similar to 
UM_DESTROY handling in a Windows window procedure. 

Your thread should call Exit- 
Thread() when it is eligible for final ter¬ 
mination via DisposeThread(). The EDI 
Threads documentation does not 
specify what happens if the thread 
simply returns without calling Exit- 
Threadf). 

You can change the characteristics 
of an active thread with SetThread- 
Priorityf) and SetThreadPause(). 
SetThreadPriorityO sets the priority 
of the specified thread to a value be¬ 
tween 100 and 1000 (higher is better). 
There is no direct correlation between 
priority and percentage of CPU utiliza¬ 
tion. EDI Threads documentation does 
not mention a priority “aging" 
mechanism. Therefore, the possibility 
exists that a low-priority task could 
starve until all higher priority tasks be¬ 
came paused or terminated. Set- 
ThreadPause() serves the dual purpose 
of suspending or resuming a thread, 
depending on the parameters. If neces¬ 
sary, you can terminate a paused 
thread via TerminateThread(), as 
described earlier. 

Last, IsThreadFinished() checks on 
the completion of a thread. Since it re¬ 
quires a thread handle parameter, the 
thread must have been started before 
you can call this function. 


Prove it to yourself at NO COST! CALL NOW! 


GlobalWare 

The Language Technology Company 


800.336.9898 (USA) 
353.1.284.4223 (Europe) 


Documentation 

The EDI Threads documentation con¬ 
sists mainly of a threads.hip Windows 
help file plus assorted header files and 
a demo program. The organization of 
the help file makes it serve as a handy 
reference. The authors have nested in¬ 
formation in easy-to-use links with 
plenty of cross-references. However, the 
help file does not contain a tutorial and 
relies mainly on your ability to study 
and understand the demo program. My 
own bias is toward documentation that 
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Figure 1 The EDI threads for Windows API 


WORD GetThrdUtlsVersion(); 

WORD GetNumThreads(VOID); 

VOID SetThrdUtlsTimeSlice(WORD ATimeSlice); 

PThreadRec CreateThread(PThreadFunc ThreadFunc, WORD StackSize, 
HWND Wnd, WORD wParam, LONG IParam); 

VOID DisposeThread(PThreadRec ‘Thread); 

WORD ExecThread(PThreadRec Thread); 

WORD YieldThread(VOID); 

VOID ExitThread(VOID); 

VOID TenriinateThread(PThreadRec Thread); 

VOID SetThreadPriority(PThreadRec Thread, WORD Priority); 
VOID SetThreadPause(PThreadRec Thread, BOOL Paused); 


| BOOL IsThreadPaused(PThreadRec Thread); 

BOOL IsThreadFinished(PThreadRec Thread); 

BOOL AddThread(PThreadRec Thread); 

VOID RemoveThread(PThreadRec Thread); 

PThreadRec StartThread(PThreadFunc ThreadFunc, WORD StackSize, 
HWND Wnd, WORD wParam, LONG IParam); 
VOID EndThread(PThreadRec ‘Thread); 

VOID ExecTaskThreads(HANDLE Task); 

| VOID EndTaskThreads(HANDLE Task); 

NOTE: all functions are actually declared "FAR PASCAL" 


can be easily printed or read online like 
a book (for example, in a .wri file). 

The demonstration program, 
threads.exe (see Figure 2), shows a set 
of random bouncing balls and lines 
where each object gets drawn by an in¬ 
dependently operating thread. While 
the program quite graphically illustrates 
the smoothness of context switching, it 
demonstrates only seven of the twenty 
API functions. Adding several more com¬ 
plete example programs might improve 
ease of learning. 

Support, Registration, and 
Licensing 

Eschalon Development, Inc. provides 
technical support for Threads For Win¬ 
dows via telephone and CompuServe e- 
mail. EDI promises to periodically pro¬ 
vide bug fixes and upgrades. You may 
contact them at any time to obtain the 
latest version. Minor changes and bug 
fixes are free, but major revisions carry 
an upgrade fee. 

You can obtain the registered ver¬ 
sion of EDI Threads for $99.95. As an ad¬ 
ditional option, the entire source code is 
available for $395. The evaluation ver¬ 
sion of thrdutls.dll always displays a 
plea for registration when first invoked. 
You must register EDI Threads before 
you can redistribute it as part of your 
product. 

Once you've registered, you may dis¬ 
tribute thrdutls.dll with your product 
without royalties or restrictions so long as 
it is used as a supplement or complement 
your own package, and not for itself. 

Conclusion 

Threads For Windows supplies a 
simple, yet highly effective method of 
introducing multithreading into your 
current windows application. With a 
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minimum of fuss, your application can perform background face. Best of all, Threads For Windows works in today’s 
operations, such as spreadsheet recalculation, printing, or popular Windows 3.1 environment, 
serial I/O, and still remain very responsive to the user inter- 



Figure 2 Bouncing-ball thread demonstration 
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A Range-Definable 
Custom Edit Control 

William Smith 


Windows comes with a broad assortment of child window classes, or controls, 
such as pushbuttons, radio buttons, listboxes, and edit controls. Some tasks require 
capabilities that these standard controls do not provide. You can create custom 
controls to solve this problem. Once you create a custom control, you can add it to 
the existing palette of Windows tools, making the custom control a seamless addi¬ 
tion to the Windows API. You can even incorporate custom controls in your 
programs by using the dialog editor that comes with the Windows SDK. You use 
custom controls in your programs the same way you use standard controls. 

One means of creating a new custom control is by “subclassing.” Subclassing an 
existing window class lets you borrow features from that class and avoid reinventing 
its behavior. The code presented here creates a custom edit control called an edit- 
range control. The edit-range control serves as a useful example of how to create a 
custom control by subclassing. This custom control borrows much of its behavior 
from the standard Windows edit control. The major difference is that the edit-range 
control accepts a style that specifies a range of characters that the user can enter: 
the control rejects all characters outside the range. This is a handy feature for 
numeric-only or alphabetic-only data entry fields. The edit-range style lets you 
generate either a beep or a message box when the user attempts to enter an 
out-of-range character. 

The range-edit custom control is written in C and contains no global or static 
variables. It is re-entrant and is a good candidate for a DLL, an important issue for 
custom controls. 


Custom Controls through Subclassing 


Subclassing in Windows involves deriving a new window class from an existing 
one. I refer to the existing class as the parent class and the new class as the sub¬ 
class. Subclassing uses the object-oriented concepts of reuse and inheritance. The 
subclass inherits attributes from the parent and uses the existing code in the parent 
class window procedure to handle most of the work. 

There are two different degrees or levels of subclassing: partial subclassing and 
complete subclassing. (These terms are my own —you may not come across them 
elsewhere, but they help convey the distinctions between the two methods). The 
fundamental difference between partial and complete subclassing is that complete 
subclassing creates and registers a new window class, while partial subclassing just 
modifies an existing window class. 

Complete subclassing has many advantages over partial subclassing. Complete 
subclassing allows you to treat the subclass as a custom control, which means you 
can perform all of the specialized custom control operations on it. These 
include the ability to integrate the custom control into a dialog editor, 
specify custom control information in resource files, and store the cus¬ 
tom control code in a DLL. 



William Smith is the engineering manager at Montana Software, a 
software development company specializing in custom applications for 
MS-DOS and Windows. You may contact him by mail at P.O. Box 663, 
Bozeman, MT 59771-0663. 
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Listing 1 subclass.c - Code to make subclassing easy 

. 

• 

!***************************************************** 

if ( hWnd == NULL ) 

File Name: SUBCLASS.C 

{ 

Description: Library of functions for 

/* Could not create a window */ 

subclassing windows. 

UnregisterClass( WndClass.lpszClassName, 

Global Function List: RegisterSubClass, GetParentClsWndProc 

WndClass.hlnstance ); 

GetSubClsIndex, GetSubWndlndex 

return ( FALSE ); 

GetSubClassLong, GetSubClassWord 

} 

GetSubWindowLong, GetSubWindowWord 


SetSubClassLong, SetSubClassWord 

/* Store the parent class info in the sub 

SetSubWindowLong, SetSubWindowWord 

** class class extra bytes */ 

Local Macro List: PARENT PROC INDEX 

SubClsClsExtra = WndClass.cbClsExtra; 

PARENT CLSEXTRA INDEX 

GetClassInfo( NULL, ParentClsName, &WndClass ); 

PARENT WNDEXTRA INDEX 

SetClassLong( hWnd, (int)SubClsClsExtra - 

Portability: MS Windows, Any memory model. 

(int)PARENT PROC INDEX, 

Any windows compatable C Compiler 

(LONG)WndClass.lpfnWndProc ); 

******************************************************/ 

SetClassWord( hWnd, (int)SubClsClsExtra - 


(int)PARENT CLSEXTRA INDEX, 

linclude <windows.h> 

(WORD)WndClass.cbClsExtra ); 

linclude "subclass.h M 

SetClassWord( hWnd, (int)SubClsClsExtra - 


(int)PARENT WNDEXTRA INDEX, 

/* Offsets of parent class window information 

(WORD)WndClass.cbWndExtra ); 

** from the end of the class extra bytes of the 

/* Set the new window proc for the class */ 

** subclass window class structure */ 

SetClassLong( hWnd, GCL WNDPROC, 

Idefine PARENT PROC INDEX ( sizeof( FARPROC ) ) 

(LONG)SubClsWndProc ); 

Idefine PARENT CLSEXTRA INDEX \ 

DestroyWindow( hWnd ); 

( sizeof( FARPROC ) + sizeof( int ) ) 

return ( TRUE ); 

Idefine PARENT WNDEXTRA INDEX \ 

} /* RegisterSubClass */ 

( sizeof( FARPROC ) + sizeof( int ) \ 


+ sizeof ( int ) ) 

/***************************************************** 


Name: GetParentClsWndProc 

/***************************************************** 

Parameters: hWnd - handle of sub classed window 

Name: RegisterSubClass 

Return: pointer to parent class window proc 

Parameters: SubClsName - string containing name of 

Description: obtained the parent window proc of a 

subclass window class 

subclassed window 

ParClsName - string containing name of 

*****************************************************/ 

parent window class 

FARPROC FAR PASCAL GetParentClsWndProc ( HWND hWnd ) 

hlnstance - handle of the Instance 

{ 

registering this subclass 

int Index; 

FARPROC - pointer to window proc for 


the subclass windows 

Index = (int)GetClassWord( hWnd, GCW CBCLSEXTRA ); 

SubClsClsExtra - number of class extra 

Index -= (int)PARENT PROC INDEX; 

bytes for the subclass 

return ( (FARPROC)GetClassLong( hWnd, Index ) ); 

SubClsWndExtra - number of window extra 

} /* function GetParentClsWndProc */ 

bytes for the subclass 


Return: TRUE for success, FALSE for failure 

/***************************************************** 

Description: 

Name: GetSubClsIndex 

Loads a WNDCLASS structure with information contained 

Parameters: hWnd - handle of subclassed window 

in an existing window class (Parent Class). This 

Index - offset of subclassed extra byte 

structure is modified to subclass window values. This 

Return: Extra byte offset index 

new subclass window class is then registered. Note - 

Description: Gets the index, byte offset, of class 

the values of style, hlcon, hCursor, hbrBackground and 

extra byte information. 

IpszMenuName remain the same as the parent class. 

*****************************************************/ 

Subclasses that require modification to these values 

int GetSubClsIndex( HWND hWnd, int Index ) 

can not use this functon and require individual 

{ 

treatment. 

if ( Index < 0 ) 

*****************************************************/ 

/* Offset Is Into window structure 

BOOL FAR PASCAL RegisterSubClass( char *SubClsName, 

** members so return unchanged */ 

char *ParentClsName, HINSTANCE hlnstance. 

return ( Index ); 

WNDPROC SubClsWndProc, 

/* Get the size of the parent class els extra 

int SubClsClsExtra, int SubClsWndExtra ) 

** bytes add to the index and return */ 

{ 

return ( Index + (int)GetClassWord( hWnd, 

HWND hWnd; 

(int)GetClassWord( hWnd, GCW CBCLSEXTRA ) 

WNDCLASS WndClass; 

- (int)PARENT CLSEXTRA INDEX ) ); 


} /* funciton GetSubClsIndex */ 

/* Load WndClass with parent class info */ 


if ( !GetClassInfo( NULL, ParentClsName, 

f ***************************************************** 

SWndClass ) ) 

Name: GetSubWndlndex 

/* Could not find the parent class */ 

Parameters: hWnd - handle of subclassed window 

return ( FALSE ); 

Index - offset of subclassed extra byte 


Return: Extra byte offset index 

/* Set class values to subclass info */ 

Description: Gets the index, byte offset, of window 

WndClass.cbClsExtra += (int)PARENT WNDEXTRA INDEX 

extra byte information. 

+ SubClsClsExtra; 

***************************************************** / 

WndClass.cbWndExtra += SubClsWndExtra; 

int GetSubWndlndex( HWND hWnd, int Index ) 

WndClass.hlnstance = hlnstance; 

{ 

WndClass.lpszClassName = SubClsName; 

if ( Index < 0 ) 


/* Offset is into window structure 

/* Regsiter the new subclass */ 

** members so return unchanged */ 

if ( !RegisterClass( &WndClass ) ) 

return ( Index ); 

/* Could not register the new class */ 

/* Get the size of the parent class wnd extra 

return ( FALSE ); 

** bytes add to the index and return */ 

hWnd = CreateWindow( SubClsName, 0, 

return ( Index + (int)GetClassWord( hWnd, 

CW USEDEFAULT, CW USEDEFAULT, 

(int)GetClassWord( hWnd, GCW CBCLSEXTRA ) 

CW USEDEFAULT, CW USEDEFAULT. 

- (int)PARENT WNDEXTRA INDEX ) ); 

NULL, NULL, hlnstance, NULL ); 

} /* funciton GetSubWndlndex */ 
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Another advantage is that complete subclassing lets you 
define and use class and window extra bytes to associate 
data with a class or window, while partial subclassing does 
not. Associating data your control needs at runtime with a 
window using the extra bytes is a handy way to avoid using 
global or static data —a necessity if you want your code to be 
re-entrant and storable in a DLL. With partial subclassing you 
must use window properties to associate data with a window. 
The difference here is that you must create and destroy the 
properties explicitly at runtime; unlike extra bytes, window 
properties are not automatically freed up by Windows when 
the window is destroyed. 

Partial subclassing works well when you need custom be¬ 
havior in a single situation (Brian Wyld's article, Making CUA- 
Compliant MLEs,” in the September, 

1991 issue is a good example). Partial 
subclassing associates a new window 
procedure with an entire class or a 
single window of that class. You ac¬ 
complish this with a call to SetClass- 
Long() or SetUindowLongO. The new 
window procedure responds to those 
messages that need to be treated dif¬ 
ferently, sending all other messages to 
the parent class window procedure. To 
create a custom control, you must use 
complete subclassing. In the remainder 
of this article, when I refer to subclass¬ 
ing, 1 am referring to complete sub¬ 
classing. 



/***************************************************** 
Name: GetSubClassLong - SetSubWindowWord 
Description: The following eight functions are 

analogous to the eight Windows functions 
GetClassLong - SetWindowWord. 

The difference is that these funcitons 
are required for accessing and setting 
extra bytes of subclassed windows. 
*****************************************************/ 

LONG FAR PASCAL GetSubClassLong( HWND hWnd, 
int nIndex ) 

{ 

nlndex = GetSubClsIndex( hWnd, nlndex ); 

return( GetClassLong( hWnd, nlndex ) ); 


A Subclassing Code Library 

The routines in subclass.c (Listing 
1) make the subclassing chores easy. 
The first task, registering the subclass, is 
performed by RegisterSubClass(). 
This is a generic function that you can 
use to register any type of subclass 
regardless of the parent class —like the 
other functions in subclass.c, it is not 
limited to use with the edit-range cus¬ 
tom control. Use the definitions in sub¬ 
class. h (Listing 2) to access the sub¬ 
class functions. 

RegisterSubClass() has some 
limitations. It does not let you change 
the values of the window class struc¬ 
ture members style, hlcon, hCursor, 
hbrBackground, and IpszMenuName from 
the values set by the parent class. If 
you need to modify these, I suggest 
you either modify RegisterSubClassf) 
or use the Windows function SetClass- 
Uord() or SetClassLongO after you 
register the subclass. To store and keep 
track of parent class information, 
RegisterSubClass() reserves some 
extra bytes in the subclass. It stores the 
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Listing 1 continued 


} /* function */ 

WORD FAR PASCAL GetSubClassWord( HWND hWnd, 
int nlndex ) 

{ 

nlndex ■ GetSubClsIndex( hWnd, nlndex ); 
return( GetClassWord( hWnd, nlndex ) ); 

} /* function GetSubClassWord */ 

LONG FAR PASCAL GetSubWindowLong( HWND hWnd, 
int nlndex ) 

{ 

nlndex » GetSubWndIndex( hWnd, nlndex ); 
return( GetWindowLong( hWnd, nlndex ) ); 

} /* function GetSubWindowLong */ 

WORD FAR PASCAL GetSubWindowWord( HWND hWnd, 
int nlndex ) 

{ 

nlndex ■ GetSubWndIndex( hWnd, nlndex ); 
return( GetWindowWord( hWnd, nlndex ) ); 

} /* function GetSubWindowWord */ 

LONG FAR PASCAL SetSubClassLong( HWND hWnd, 
int nlndex, LONG NewLong ) 

{ 

nlndex • GetSubClsIndex( hWnd, nlndex ); 
return( SetClassLong( hWnd, nlndex, NewLong ) ); 

} /* function SetSubClassLong */ 

WORD FAR PASCAL SetSubClassWord( HWND hWnd, 
int nlndex, WORD wNewWord ) 

{ 

nlndex » GetSubClsIndex( hWnd, nlndex ); 

return( SetClassWord( hWnd, nlndex, wNewWord ) ); 

} /* funciton SetSubClassWord */ 

LONG FAR PASCAL SetSubWindowLong( HWND hWnd, 
int nlndex, LONG NewLong ) 

{ 

nlndex = GetSubWndIndex( hWnd, nlndex ); 

return( SetWindowLong( hWnd, nlndex, NewLong ) ); 

} /* function SetSubWindowLong */ 

WORD FAR PASCAL SetSubWindowWord( HWND hWnd, 
int nlndex, WORD wNewWord ) 

{ 

nlndex » GetSubWndIndex( hWnd, nlndex ); 

return( SetWindowWord( hWnd, nlndex, wNewWord ) ); 

} /* SetSubWindowWord */ 

/* End of File */ 


Listing 2 subclass.h - Header file for subclass.c 


1 *++ ************************************************** 
File Name: SUBCLASS.H 
Description: include file for SUBCLASS.C 
Portability: MS Windows, Any memory model, 

Any windows compatable C Compiler 
******************************************************/ 
#if !defined( SUBCLASS_DEFINED ) 

BOOL FAR PASCAL RegisterSubClass( 

char *SubClsName, char *ParClsName, 

HINSTANCE hlnstance, 

WNDPROC SubClsWndProc, 

int SubClsClsExtra, int SubClsWndExtra ); 

FARPROC FAR PASCAL GetParentClsWndProc( 

HWND hWnd ); 

int GetSubClsIndex( HWND hWnd, int Index ); 

int GetSubWndIndex( HWND hWnd, int Index ); 

LONG FAR PASCAL GetSubClassLong( HWND hWnd, 
int nlndex ); 

WORD FAR PASCAL GetSubClassWord( HWND hWnd, 
int nlndex ); 

LONG FAR PASCAL GetSubWindowLong( HWND hWnd, 
int nlndex ); 

WORD FAR PASCAL GetSubWindowWord( HWND hWnd, 
int nlndex ); 

LONG FAR PASCAL SetSubClassLong( HWND hWnd, 
int nlndex, LONG NewLong ); 

WORD FAR PASCAL SetSubClassWord( HWND hWnd, 
int nlndex, WORD wNewWord ); 

LONG FAR PASCAL SetSubWindowLong( HWND hWnd, 
int nlndex, LONG NewLong ); 

WORD FAR PASCAL SetSubWindowWord( HWND hWnd, 
int nlndex, WORD wNewWord ); 

Idefine SUBCLASS_DEFINED 
#endif 

/* End of File */ 


parent class window procedure and parent class extra byte 
values in the subclass extra bytes. 

The other functions in subclass.c (Listing 1) perform tasks 
required for dealing with subclassed windows. GetParentCls- 
WndProc() obtains a pointer to the window procedure of the 
parent class. The subclass window procedure uses this pointer 
to pass window messages to the parent class window proce¬ 
dure for default processing, letting it handle most of the work 
(painting the control, handling keystrokes and the text caret, 
and so on). 


Listing 3 editrang.c — Range-restricted edit 
control code 


I ***************************************************** 

File Name: EDITRANG.C 
Description: Library of functions for 
edit range custom control 
Global Function List: EditRangeProc 
Static Function List: IsCharType 

Portability: MS Windows, Any memory model. 

Any windows compatable C Compiler 


linclude <ctype.h> 

#include <string.h> 
linclude <windows.h> 
linclude "subclass.h" 
linclude "editrang.h" 

/* Static function prototypes */ 

static int IsCharType( int Char, WORD Type ); 

I ***************************************************** 

Name: EditRangeProc 

Description: Window proc for edit range custom control 
window class. 

*****************************************************/ 

LONG CALLBACK EditRangeProc( HWND hWnd, 

UINT wMessage, WPARAM wParam, LPARAM IParam ) 

{ 

BOOL CharlnRange; 

if ( wMessage == WM_CREATE ) 

{ 

WORD Style; 

LONG Special Chars; 

/* Set the default style that is in the class 
** extra bytes. */ 

Style = GetSubClassWord( hWnd, OFFSETJTYLE ); 
SetSubWindowWord( hWnd, OFFSET_STYLE, Style ); 
SpecialChars = GetSubClassLong( hWnd, 

OFFSET SPECIALCHARS ); 

SetSubWindowLong( hWnd, OFFSET_SPECIALCHARS, 
SpecialChars ); 

} /* if wMessage */ 

if ( wMessage == WM_CHAR ) 

{ 

int AsciiChar; 

WORD Style, Type; 

AsciiChar = (int)wParam; 

/* Retrieve the style from the window 
** property list */ 

Style = GetSubWindowWord( hWnd, OFFSET_STYLE ); 

if ( Style & ERS_T0L0WER ) 

{ 

/* Convert the charater to lower case */ 
AsciiChar = tolower( AsciiChar ); 
wParam = (WORD)AsciiChar; 

1 

if ( Style & ERS TOUPPER ) 

( 

/* Convert the charater to upper case */ 
AsciiChar = toupper( AsciiChar ); 
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The functions GetSubClassLongO through SetSubUindow- 
Word() retrieve and set information in the class and window 
extra bytes of the subclass. In subclassed windows, you must 
use these functions rather than the Windows functions Get- 
ClassLongO through SetWindoMord() in order to protect the 
parent class extra bytes. These functions perform the book¬ 
keeping required to index the extra bytes that may be used 
by the parent class window procedure. 


Listing 3 continued 


wParam = (WORD)AsciiChar; 

} 

CharlnRange = FALSE; 

Type = ERS_ALNUM; 

while ( ICharlnRange && Type <= ERS XDIGIT ) 

{ 

/* Loop through all the style types */ 
if ( Style & Type ) 

{ 

/* Check if character is this type */ 
CharlnRange = IsCharType( AsciiChar, 

Type ); 

} 

Type «= 1; 

} /* while */ 

if ( ICharlnRange && ( Style & ERS SPECIAL ) ) 

{ 

LPSTR Special Chars; 

/* Get the Special Chars pointer from the 
** window property list. */ 

Special Chars = (LPSTR)GetSubWindowLong( 
hWnd, OFFSET_SPECIALCHARS ); 
if ( ( Special Chars != NULL ) && 

( _fstrchr( Special Chars, 

(char)AsciiChar ) != NULL ) ) 
CharlnRange = TRUE; 

} /* if ICharlnRange */ 

if ( ICharlnRange ) 

{ 

if ( Style & ERS_BEEP ) 

MessageBeep( 0 ); 
if ( Style & ERS_MESSAGE ) 

{ 

MessageBox( hWnd, "You are attempting " 

"to enter characters that " 

"are outside the valid range " 

"for this edit field.", NULL, 
MB_IC0NINF0RMATI0N | MB_0K ); 
SetFocus( hWnd ); 

} 

} /* if ICharlnRange */ 

} /* if wMessage */ 

if ( CharlnRange || wMessage != WM CHAR ) 

{ 

FARPROC EditWndProc; 

/* Pass message to the parent els wnd proc */ 
EditWndProc = GetParentClsWndProc( hWnd ); 
if ( EditWndProc != NULL ) 

return ( CallWindowProc( (WNDPROC)EditWndProc, 
hWnd, wMessage, wParam, 

IParam ) ); 

} /* if CharlnRange */ 

return ( TRUE ); 

} /* function EditCharRangeProc */ 

^***************************************************** 
Name: IsCharType 

Parameters: Char - ASCII character 

Type - type of character to check for 
Return: TRUE if character type match else FALSE 
Description: Checks to see if a character is a 
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Listing 3 continued 


specified type. 

*****************************************************/ 
static Int IsCharType( 1nt Char, WORD Type ) 

( 

switch ( Type ) 

{ 

case ERS_ALNUM: return( 1salnum( Char ) ); 

case ERS_ALPHA: return) Isalpha) Char ) ); 

case ERS_CNTRL: return) iscntrl) Char ) ); 

case ERS_DIGIT: return) isdiglt) Char ) ); 

case ERS~GRAPH: return) Isgraph) Char ) ); 

case ERS_LOWER: return) islower) Char ) ); 

case ERS_PRINT: return) isprint) Char ) ); 

case ERS'PUNCT: return) Ispunct) Char ) ); 

case ERS_SPACE: return) isspace) Char ) ); 

case ERSJJPPER: return) Isupper) Char ) ); 

case ERS”XDIGIT: return) isxdigit) Char ) ); 
default: return ( FALSE ); 

) 

) /* function IsCharType */ 

/* End of File */ 


The Edit-Range Custom Control 

editrang.c (Listing 3) contains the code for the edit-range 
window procedure, EditRangeProc(). You set the edit-range 
style with a bit flag; the style is stored in the window extra 
bytes for easy access. The possible edit-range styles, 
ERS_ALNUM through ERS_TOUPPER, are equivalent to the Stand¬ 
ard C functions, isalnuw() through toupper(), defined in the 
Standard C include file ctype.h. editrang.h (Listing 4) con¬ 
tains definitions of all the possible edit-range styles. The static 
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function IsCharType() in editrang.c checks to see if a char¬ 
acter is within range. IsCharType () maps each style bit to the 
corresponding Standard C library function. If the function 
returns TRUE, the character is within range. 

You can use a special range style, ERS_SPECIAL, to limit 
the range within a set of specified characters. The window 
extra bytes contain a pointer to these specified characters. 
The EditRangeProc() uses the function GetSubWindowLongO 
to retrieve this pointer. 

Two style bits control the response to out-of-range charac¬ 
ters. The first, ERS_BEEP, generates a beep if the user attempts 
to input an out-of-range character. The second, ERS_MESSAGE, 
generates a message box explaining that the user attempted 
to input an out-of-range character. You can combine any of 
the styles by Ofiing them together. 

As an example, for a laboratory data acquisition application 
that requires the user to enter a floating-point number, I use 
the following style to define the edit-range control: 

Style = ( ERSDIGIT | 

ERS_CNTRL | 

ERS_SPECIAL ); 

This control only accepts characters for floating-point num¬ 
bers. Note the use of the ERS_CNTRL style. You must set this 
style so the edit-range control will accept editing keystrokes 
such as the backspace. Floating-point numbers also require 
some special characters other than digits. The special charac¬ 
ter string for floating-point numbers is 

Special Chars [] = "-+eE."; 

In addition to the m_CHAR message, the edit-range win¬ 
dow procedure, EditRangeProc() , also responds to the 
WM_CREATE message. On receiving a UM_CREATE message, Edit- 
RangeProc() sets the window extra bytes for style and spe¬ 
cial characters to the default values, which are contained in 
the class extra bytes. EditRangeProcf) sends all other mes¬ 
sages back to the parent class window procedure. 

Using the Edit-Range Control 

To use the edit-range control, you must first register the 
window class. You can do this either in the UinMain() func¬ 
tion of your program or, if you are storing the code in a DLL, 
in the LibMain() function. The following code registers the 
edit-range class. 

RegisterSubClass( 

"EDITRANGE", 

"EDIT", 

hlnstance, 

EditRangeProc, 

ER_CLSEXTRA, 

ER_WNDEXTRA ); 

ER_CLSEXTRA and ER_UNDEXTRA are constants that specify the 
number of extra bytes required to store the style, special 
characters pointer, and an internal flag that is user defined. 
editrang.h (Listing 4) defines these constants. Once you have 
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registered the class, you can set the class extra bytes to the 
style and, if needed, the special characters. Subsequently, 
every window created will have the specified style and special 
characters as a default. The following code excerpt shows how 
to do this: 

SetSubClassWord( hWnd, OFFSET_STYLE, Style ); 
SetSubClassLong( hWnd, OFFSET_SPECIALCHARS, Chars ); 

Listing 4 editrang.h - Header file for editrang.c 

^***************************************************** 


File Name: EDITRANG.H 

/* produce a beep when a character is rejected */ 

Description: Include file for EDITRANG.C 

#define ERS BEEP 8192 

Portability: MS Windows, Any memory model, 

/* produce message box when a character is rejected */ 

Any windows compatable C Compiler 

#define ERS MESSAGE 16384 

★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★A:************** Ir-k-k-k ^ 

/* specify a special range of characters */ 

# if ! defined ( EDITRANG_DEFINED ) 

fdefine ERS_SPECIAL 32768 

/* Styles corresponding to 

/* Byte offsets for acessing data */ 

** functions in ctype.h 

Idefine OFFSET STYLE 0 

** ECRS is short for: 

Idefine OFFSET SPECIALCHARS sizeoff WORD ) 

** Edit Range Style */ 

#define OFFSET MEMFLAG ( OFFSET SPECIALCHARS + \ 

fdefine ERS ALNUM 1 

sizeof ( LPSTR ) ) 

#define ERS ALPHA 2 

#define ER WNDEXTRA (int) ( sizeof ( WORD ) + \ 

#define ERS CNTRL 4 

sizeoff LPSTR ) + sizeoff WORD ) ) 

#define ERS DIGIT 8 

#define ER CLSEXTRA (int) ( sizeoff WORD ) + \ 

Idefine ERS GRAPH 16 

sizeof( LPSTR ) + sizeoff FARPROC ) ) 

#define ERS LOWER 32 


Adefine ERS PRINT 64 

LRESULT CALLBACK EditRangeProcf HWND hWnd, 

#define ERS PUNCT 128 

UINT wMessage, WPARAM wParam, LPARAM IParam ); 

#define ERS SPACE 256 

#define EDITRANG DEFINED 

#define ERS UPPER 512 

lendif 

#define ERS XDIGIT 1024 

/* End of File */ 

#define ERS TOLOWER 2048 


fdefine ERS TOUPPER 4096 
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editrang.h also contains the index constants 0F- 
FSET_STYLE and OFFSETJPECIALCHARS. To set the class extra 
bytes you need a window handle-, if no window exists, you 


may have to create a temporary window of the subclass with 
CreateUindow(). The edit-range window is created automat¬ 
ically if the control is specified in a resource script file; other¬ 
wise, you must use the function CreateUindov/(). Once you 
have created an edit-range window, you can set the style and 
special characters for this particular window as follows. 

SetSubWindowWord( hWnd, OFFSET_STYLE, Style ); 

SetSubWindowLong( hWnd, OFFSET_SPECIALCHARS, Chars ); 

The code disk contains the source code, resource scripts, 
makefile, etc., for a program that demonstrates the edit-range 
control. The demo program has a dialog box (see Figure 1) 
that contains a checkbox for each of the possible edit-range 
styles. There is also an edit field for specifying the special 
character list. All these controls are in a group box. Outside 
the group box is a edit-range control. This program allows you 
to test all the possible combinations of styles. I found it quite 
interesting to experiment and see which characters cor¬ 
responded to which of the Standard C functions in ctype.h. 

Conclusions 

You can use the edit-range control presented here in two 
ways: as an example of creating a custom control through 
subclassing and/or as an actual control in your application. In 
either case, you'll find that it provides a powerful and con¬ 
venient means of extending Windows' functionality. □ 
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Reader-Contributed Tricks and Hacks 



Edited by 
Leor Zolman 


Please send us your best 
tricks and hacks —those 
clever pieces of code to 
make things work the 
way they should! You’ll 
receive at least $50 for 
each tip that we print 
Send your submissions to.- 
Tech Tips 
Leor Zolman 
74 Marblehead Street 
North Reading, MA 01864 
Ieor@bdsoft.com. 


More Stupid .BAT Tricks and a 
Clever Database Converter 

Fast Switching between Borland 
and Microsoft Compilers 


Leor Zolman 
74 Marblehead St 
North Reading, MA 01864 


In editing this column, I often need to switch back and forth between the 
Microsoft and Borland C compiler packages. Most programmers probably have a 
favorite compiler, yet may need to use other packages from time to time in order to 
test portability or compile code that uses some proprietary functions (for example, 
Larry Hansen's program later in this column is tied to Microsoft C due to the screen 
handling). 

The usual solution for supporting multiple development environments is to have 
a customized autoexec.bat file for each environment, then copy the appropriate 
version into the boot directory (either manually or via a controlling batch file) and 
reboot DOS each time a different compiler is needed. This may be okay for oc¬ 
casional switches, but it becomes tedious if more frequent compiler-hopping is re¬ 
quired. 

To eliminate the need to reboot DOS, 1 created a set of batch files that support 
speedy dynamic switching between any number of compiler environments as often 
as desired. In addition to setting the standard environment variables (the path, LIB, 
INCLUDE, etc.) for each development system, my batch files also support automatic 
command recall for the most recent makefile invocation, explicit compiler command, 
and text editor session (using the technique 1 first presented in the January 1993 
Tech Tips column). 

The two master batch files are BPATH.BAT (Listing 1), for setting up a Borland 
compiler environment, and MPATH.BAT (Listing 2), for setting up a Microsoft compiler 
environment. Both of these files assume that an environment variable named COM¬ 
MON PATH is initialized in autoexec.bat to contain all the directories you want in your 
system path except the “executables" directories of any compiler packages. For ex¬ 
ample, Listing 3 shows how the definitions of COMMON PATH and PATH appear in my 
autoexec.bat file. By leaving the compiler directories out of the common system 
path, I can construct a full system path at any time by appending a new compiler’s 
binary directory onto the common system path list without having to worry about 
"stripping off’ a previous compiler’s entry. 



Leor Zolman wrote BDS Q the first C compiler targeted exclusively for personal computers. 
Leor is currently an instructor on UNIX topics for Boston University’s Corporate Education 
Center, a regular contributor to Sys Admin magazine and “Tech Tips" editor for Win- 
dows/DOS Developer’s Journal. His /irst book, Illustrated C, was published by R&D Publica¬ 
tions, Inc in 1992. He may be contacted at 74 Marblehead St, North Reading, MA 01864, 
or on Usenet/lntemet as.- leor@bdsoft.com. 






















The two master batch files each cre¬ 
ate an environment variable named 
COMPILER containing the command-line 
compiler command (bcc or cl) ap¬ 
propriate to their environment. This 
variable is used by C.BAT (described 
later). The batch files also initialize the 
environment variables used by the make 
files in Charles Petzold’s Programming 
Windows 3.1, allowing all the programs 
in that book to be compiled using 
M.BAT (also described later). 

I’ve enhanced my C.BAT batch file 
(see January 1993 Tech Tips) to use the 
value of COMPILER as the command 
name when issuing compiler commands 
(Listing 4). For example, if I've already 
given the mpath command to work with 
Microsoft C, and I then issue the com¬ 
piler request: 

c /F 1000 /Zi fimport.c 

then the next time I type the simple 
command: 

c 


Notice to Our 
Subscribers 

Occasionally, Windows/DOS 
Developer’s Journal makes its 
mailing list available to vendors 
of products we think our 
readers will find interesting. Cur¬ 
rent subscribers receive free in¬ 
formation in the mail from 
these vendors. 

If you prefer that your name 
not be used in these mailings, 
please let us know. Just copy or 
clip this form and send it with 
your name and address to: 


Windows/POS 

□ DEVELOPER'S JOURNAL 

1601 W. 23rd. St., Suite 200 
Lawrence, KS 66046-2743 


Listing 1 bpath.bat 


@echo off 
rem 

rem BPATH.BAT: Set up for Borland C++ 3.1 command line execution: 
rem 

set path=d:\bc\bin;%C0MM0NPATH% 

set INCLUDE=d:\bc\owl\include;d:\bc\classl ib\include;d:\bc\include 
set LIB=d:\bc\owl\lib;d:\bc\classlib\lib;d:\bc\lib 
set C0MPILER=bcc 

rem- 

rem BCP.BAT -- Set up environment for Borland C++ 3.1 MAKE 

rem- 

set WINCC=bcc -c -w-par -P -W -2 

set WINLINK=tlink /c /n /Tw /Ld:\bc\lib cOws 

set WINLIB=import mathws cws 

set WINRC=rc -r -id:\bc\include 

rem- 

rem BCPDLL.BAT — set up environment for Borland C++ 3.0 MAKE 

rem--- 

set DLLCC=bcc -c -ms! -w-par -P -W -2 
set DLLLINK=tlink /c /n /Tw /Ld:\bc\lib cOds 
set DLLLIB=import mathws cws 
set DLLRC=rc -r -id:\bc\include 

echo Environment / m command set up for Borland compiler. 


Listing 2 mpath.bat 


Oecho off 
rem 

rem MPATH.BAT: Set up for Microsoft Visual C++ command line execution: 
rem 

set path=d:\msvc\bin;%C0MM0NPATH% 
set T00LR00TDIR=D:\MSVC 

set INCLUDE=D:\MSVC\INCLUDE;D:\MSVC\MFC\INCLUDE 
set LIB=D:\MSVC\LIB;D:\MSVC\MFC\LIB 
set INIT=D:\MSVC 
set C0MPILER=cl 

REM. 

REM MSC.BAT — Set up environment for Microsoft C/C++ 7.0 NMAKE 

REM. 

SET WINCC=cl -c -G2sw -Ow -W3 -Zp -Tp 
SET WINLINK=1ink /nod 

SET WINLIB=slibcew oldnames libw commdlg ddeml 
SET WINRC=rc -r 

REM. 

REM MSCDLL.BAT -- Set up environment for Microsoft C 7.0 NMAKE 

REM. 

SET DLLCC=cl -c -ASw -G2sw -Ow -W3 -Zp -Tp 
SET DLLUNK=link /nod libentry 
SET DLLLIB=sdllcew oldnames libw 
SET DLLRC=rc -r 

echo Environment / m command set up for Microsoft compiler. 


Listing 3 autoexec.bat fragment 


rem Pecho off 

rem Beginning portion of my AUTOEXEC.BAT, showing initialization 
rem of COMMONPATH and PATH for use with the BPATH/MPATH batch files: 
rem 

set COMMONPATH=c:\bin;c:\bat;c:\dos;c:\sys\nu;c:\windows;e:\ndw; 
set PATH=%COMMONPATH% 
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Listing 4 c.bat 


C.BAT: Compile a program, and recall last explicit set of parameters 
rem if no filename is specified. Written by Leor Zolman, 11/92 
rem 

rem Usage: 

rem c [command line parameters] - save cmd line image 

rem c - re-issue saved image 

rem 

set APP=%COMPILER% 

if "%i" [= ”« goto explicit 
if "%1astcompi le" != "" goto run 

echo You have not specified a command yet; 
echo please enter an explicit command line! 
goto end 

: explicit 

set 1astcompi1e=%APP %1 %2 %3 %4 %5 %6 %7 %8 %9 

echo Setting command line to "%1astcompile“ and executing. . . 

goto run2 

:run 

echo Executing the command: %1astcompi1e. . . 

:run2 

%1astcompile 
:end 


Listing 5 m.bat 


m.BAT: Run a NMAKE, and recall last explicit set of parameters 
rem if no filename is specified. Written by Leor Zolman, 11/92 

rem 

rem Usage: 

rem m [command line parameters] - save cmd line image 

rem m - re-issue saved image 

rem 

rem Set up for Microsoft Compiler: 
set APP=nmake /f 
set MAKEXT=.mak 

if %C0MPILER% == cl goto checkarg 

rem Set up for Borland Compiler: 
set APP=make -f 
set MAKEXT= 

:checkarg 

if "%1" != "" goto explicit 
if "%lastmake" != "" goto run 

echo You have not specified a command yet; 
echo please enter an explicit command line! 
goto end 

:explicit 

set 1 astmake=%APP %1%MAKEXT% %2 %3 %4 %5 %6 %7 %8 %9 
echo Setting command line to "%lastmake" and executing. . . 
goto run2 

:run 

echo Executing: %lastmake. . . 

:run2 

%lastmake 

:end 


SLATE SLATE- SCRIPT 

Graphics S PRINT 

Would Text and Graphic 
Printer support for over 850 
printers give you an edge? 

By including SLATE with Graphics, you 
can print Text and Graphics on over 850 
printers. Immediately! Painlessly! 

You can use SLATE in your product 
with no royalties. It gets you out of the 
printer support business. 

Make your product more functional 
and competitive by using SLATE'S 
advanced text features: 

• Output to parallel printers, serial printers, DOS 

files and Novell network printers. 

• Support proportional fonts and scalable fonts. 

• Set exact print positions. 

• Kerning, leading, underlining, and strike through. 

• Automatic character set conversion. 

• Print lines and shaded areas (laser printers only). 

SLATE with Graphics adds advanced 
graphic printing features: 

• Print images from the screen, PCX or TIFF files, 

or custom image systems. 

• Print lines and shaded areas on all printers. 

• Scale and Rotate printed image. 

• Print grey scale and color images. 

• Intermix text and graphics. 

SLATE is a C or Basic library of over 
170 text printing functions, a Database 
of over 850 printers, and End User 
configuration and testing programs. 
SLATE with Graphics adds over 60 
graphic printing functions. 

Would a User Configurable 
Report Writer give you a 
more competitive product? 

SCRIPT is a full featured Text 
Formatting library that can be 
incorporated into your application. 
SCRIPT uses SLATE as its printer 
driver. SCRIPT lets you merge text, 
data, and S_PRINT formatting 
commands from ASCII files and your 
application. 

Enhance your product by taking 
advantage of SCRIPT'S features: 

• Allow users to alter document format. 

• Set exact positions, center, right adjust, and 

decimal align. 

• Fill paragraphs from unformatted text. 

• Add lines, shaded areas, logos, signatures, etc. 

• Add commands and macros. 

Call or FAX now for a complete catalog 
and developer's guide for The 
Symmetry Group's printer support 
products. Order SLATE for $299, 
SLATE with Graphics for $448, or 
SCRIPT for $199 with our risk free, 30 
day return policy. 


The 

Symmetry 

Group 


800-346-3938 

PO Box 26195 
Columbus, OH 43226, USA 


614-431 -2667 • FAX 614-431 -5734 
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the result will be the same as if I'd 
typed out the full command: 

cl /F 1000 /Zi fimport.c 

I've extended the principle to automate 
make runs as well. The command-line 
format for running a make is slightly dif¬ 
ferent between the Borland and 
Microsoft environments, so my auto¬ 
matic make driver M.BAT (Listing 5) 
checks which compiler is currently con¬ 
figured and makes adjustments accord¬ 
ingly. Under the Microsoft environment, 
NMAKE is used with the If flag, and the 
.mak extension is explicitly tacked onto 
the target filename. Under the Borland 
environment, the command is just MAKE 
with no default options and no exten¬ 
sion on the target name. Thus, regard¬ 
less of which compiler environment is 
currently configured, a make on a file 
named, say, foo.mak would be invoked 


m foo 

and a re-run could then be invoked by: 
m 

For convenience, I've also included 
one additional batch file, E.BAT (Listing 
6) for recording and re-issuing editor 
commands a la C.BAT and M.BAT. This 
comes in handy during command-line 
based compile-edit cycles. Just set APP 
to the command name (and options, if 
required) of your favorite programming 
editor. 

Be sure you’ve got ample environ¬ 
ment space before installing this code. 
You’ll probably need several hundred 
more bytes to support all the extra 
variables. 

Finally, note that any number of ad¬ 
ditional compiler packages can be sup¬ 
ported simply by creating a new 
xPATH.BAT master batch file for each 
(and tweaking M.BAT as required). You 


by: 


Listing 6 e.bat 


rem @echo off 

rem E.BAT: Edit file(s), and recall last explicit set of parameters 

rem if no filename is specified. Written by Leor Zolman, 11/92 

rem 

rem Usage: 

rem e [command line parameters] - save cmd line image 

rem e - re-issue saved image 

rem 

set APP=eps 

if "%1" != 11 " goto explicit 
if "%laste" != 11 " goto run 

echo You have not specified a filename yet; 
echo assuming you want to edit an empty file, 
pause 
eps 

goto end 
explicit 

set laste=%APP %1 %2 %3 %4 %5 %6 %7 %8 %9 

echo Setting command line to "%laste" and executing. . . 

goto run2 

:run 

echo Executing: %laste. . . 

:run2 

%laste 

sc 

:end 
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Listing 7 fimport.c 


* FIMPORT.C: 

* Interactive fixed-length to variable-length field conversion utility 

* Written by Larry Hansen 

* Compile/Link (Microsoft C): 

* cl /F 1000 fimport.c 
*/ 

linclude <stdio.h> 
linclude <string.h> 
linclude <graph.h> 
linclude <ctype.h> 
linclude <stdlib.h> 

void translate_fields(void); 

i nt start[250],1en[250]; 
int field; 

FILE *in, *out; 
int x; 

char inbuf[2048]; 
char infi 1 e[80] ,outfile[80]; 

main () 

{ 

FILE *imp_file,*fopen(); 
int line len,k; 

char inpath[_MAX_PATH], outpath[ MAX_PATH]; 
char drive[_MAX_DRIVE], dir[_MAX~DIR]; 
char fname[_MAX_FNAME], ext[_MAX_EXT]; 

_clearscreen(_GCLEARSCREEN); 

_settextposition(l,l); 

_outtext("Please enter the file you wish to convert:"); 
gets(infile); 

_settextposition(2,l); 

_outtext("Please enter the file you wish to save to:"); } 

gets(outfile); 

if( (in = fopen(infile,"r")) == NULL) /* 

{ 

printf("Could not open fi1e\n"); 
exit(l); 

} 

_splitpath( outfile, drive, dir, fname, ext ); 

/* File extension to save definitions in for later use: */ 
strcpy( ext, "imp" ); 

_makepath( outpath, drive, dir, fname, ext ); 

/* If definition file exists, then use it to break out the line: */ 
if(check file(outpath)) 

{ 

translate_fields(); 
exit(0); “ 

} 

/* No definition file exists. Get the first line of the input file: */ 
fgets(inbuf,2048,in); 
line_len = strlen(inbuf); 
i f (i nbuf [1 i ne__l en - 1] == ' \n') 
inbuf[line_len - 1] =0; 
fclose(in); 

/* Have user assign field markers until he is happy: */ 

do 

{ 

_settextposition(8,l); 

_outtext("Mark fields: F / space / Q..."); 

_settextposition(4, 1); 

_outtext(inbuf); 

for (x = line_len % 80; x < 80; x++) 

_outtext(" "); 
fld_break( inbuf); 

_settextposition(4, linejen); 

_settextposition(8, 1); 

_outtext("Is this information correct? "); 
k = getch(); 

} while(toupper(k) != 'Y'); 

/* Apply the conversion: */ 
translate_fields(); 

/* Save the field definitions for later re-use: */ 


imp_file = fopen(outpath,"w"); 
fprintf(imp_file, "%s\n", infile); 
for(x = 0; x < field; x++) 

fprintf(imp file, "%d %d\n", start[x], len[x]); 
fclose(imp_fileJ; 

_settextposition(10,l); 


void translate_fields(void) 

{ 

/* Open the definition file */ 
if( (in = fopen(infile,"r")) == NULL) 

{ 

printf("Could not open file\n"); 
exit(l); 

} 

/* Open the output file: */ 
out = fopen(outfile,"w"); 

/* read the input file a line at a time */ 
while(fgets(inbuf,2048,in) != NULL) 

{ 

_settextposition(4,l); 
for(x = 0; x < field - 1; x++) 

{ 

/* Print out each line: */ 
printf("\"%.*s\",",len[x],&inbuf[start [x]]); 
fprintf(out,"\"%.*s\",",len[x].iinbuf[start[x]]); 

} 

/* Do the last field: */ 
printf("\"%.*s\"\n",len[x],&inbuf[start[x]]); 
fprintf(out,"\"%.*s\"\n",len[x],&inbuf[start[x]]); 

} 

/* Close and get out */ 
fclose(in); 
fclose(out); 


fld_break(char *): Let user break line up into fields interactively 
Takes the first line of the file to be converted as the argument. 
Populates the field count, start and len arrays. 

* Field marking commands: 

* An "f" marks the current column as the last column of a field; 

* Enter or "q" ends the marking process, registering all chars past last 

* marked column as the final field; 

* "bs" backspaces to the previous column. 

* Any other char advances cursor one position to the right. 

*/ 

fld_break(char *buf) 

{ 

int old_bk_color, old_fg_color; 

int new_bk_color, new_fg_color, mark_color; 

int st_count, l_count; 

int buf_index; 

int x, y; 

int max_len, k; 

char tmp[2]; /* 2-char array for Microsoft's _outtext */ 

max_len = strlen(buf); 

0 ld_bk_ co lor = _getbkcolor(); /* Save the old colors */ 

0 ld_fg_ co l°r = _gettextcolor(); 

new_bk_color =1; /* Blue */ 

new_fg_color =15; /* bright white */ 

mark_color =2; /* green */ 

_setbkcolor((long)new_bk_color); 

_settextcolor(new_fg_color); 

/* screen positions: */ 
x = 4; 

y = 1; 

/* initialize counters to 0: */ 
buf_index = 0; 
st_count = 0; 
l_count = 0; 
field = 0; 

_settextposition(x,y); 

do 
{ 
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Part of my work involves pulling data off the mainframe 
computer and putting that data into fixed-length carriage- 
return, line-feed files that can then be imported into a 
database such as Paradox or a spreadsheet such as Lotus. 

In the past data processing wrote individual programs to 
format these fixed-length files into quoted, comma-delimited 
strings for import into commercial applications. This process 
was tedious, and often required several compile/debug cycles 
to get everything just right. This drove us to create /import, c, 
a pictorial means of converting these flat files. The source 
code is shown in Listing 7. 

The user specifies the name of the file containing the input 
data to be converted, the name of the output file, and (op¬ 
tionally) the last column position of each fixed-length field. If 
no .imp file with the basename of the output data file is 


Listing 7 continued 


settextposition(x,y); 

settextcolor(new fg color); 

/* Make a string out of the individual chars in the line: */ 

setbkcolor((long)mark color); 

tmp[0] = buf[buf index]; 

break; 

tmp[1] = 0; 


k = getch(); 

case 'Q': 

switch (toupper(k)) 

case 1 \r 1 : 

i 

/* quit: get the rest of the line and put it in 

case ’\b': /* backing up a position */ 

one big field if need be: */ 

/* decrement the arrays: */ 

start[field] = buf index ? st count : 0; 

1 count--; 

len[field] = max len - st count; 

if (1 count < 0) 

field++; 

1 count = 0; 

1 count = 0; 

buf index--; 

buf index = max len; 

if (buf index < 0) 

break; 

buf index = 0; 


/* horizontal movement: */ 

default: 

y—i 

/* I use the space bar. But pressing any character 

if (y < i) 

moves one position to the right. */ 

1 

1 count++; 

/* more than one line: */ 

y++; 

if (X > 4) 

setbkcolor((long)new bk color); 

( 

settextcolor(new fg color); 

y = 80; 
x--; 

break; 

i 

} 

/* only one line or at start of line: */ 

outtext(tmp); 

else 

if (y > 80 ) 

y - l; 

( 

) 

y - l; 

settextposition(x, y); 

x++; 

} 

setbkcolor((long)old bk color); 

buf index++; 

_settextcolor(old_fg_color); 

} while(buf_index < maxjen); 

tmp[0] = buf[buf index]; 

settextposition(4,l); 

tmp[l] * 0; 

for(x = 0;x < field - l;x++) 

/* Handle case of backspacing over field marker: */ 

printf("\"%.*s\",",len[x],&buf[start[x]]); 
printf("\"%.*s\"\n",len[x],&buf[start[x]]); 

if (field && (start[field - 1] + 1 en[field - 1] - 1) 

_setbkcolor((long)old_bk_color); 
settextcolor(old fg color); 

== buf_index) 

i 

field--; 


1 count = buf index - start[field]; 

int check file(char *fname) 

st count = start[field]; 

f 

} 

FILE *fp, *fopen(); 

/* decrement one more time because buf index 

char in_buf[80]; 
int x; 

gets incremented later in the loop: */ 


buf index--; 

if( (fp = fopen(fname,"r")) == NULL) 

break; 

return 0; 

case 'F 1 : 

fgets(in_buf,80,fp); /* infile name */ 

x = 0; 

/* Where in the line do we start? */ 

while(fgets(in buf,80,fp) != NULL) 

start[field] = st count; 

( 

/* how many chars in this field? */ 

sscanf(in buf,"%d %d",&start[x],&len[x]); 

len[field] = ++1 count; 

x++; 

/* bump the field count */ 

) 

field++; 

field = x; 

y++; 

return x; 

1 count = 0; 

i 

st count = buf index + 1; 

/* End of File */ 




shouldn’t have to worry about increasing environment space 
when adding new compilers, however, because the same 
basic set of environment variables will be recycled at each 
compiler change. 

Interactive Fixed-to-Variable-Length 
Field Conversion 


Larry Hansen 
Family Dollar Stores 
P.O. BOX 1017 
Charlotte, NC 28201-1017 



Page 68 — Windows/DOS Developer’s Journal 


September 1993 

















found, fimport.exe puts the first fixed-length record (line) of 
the input file up on the screen with the cursor over column 
one. The user may then use the space bar, T, backspace and 
Enter keys to mark the last column of each field. Each column 
must be registered with either a space or an T. Separate 
colors are used to denote marked columns (the last columns 
of each field), unmarked columns, and columns that have not 
yet been processed. 

When the user has finished marking the first record in the 
file, the program takes off and does the rest. It even stores 
the field definitions in another file (having the base name of 
the output file and the extension . imp) so that the user can 
process another input file of the same name at a later time 
without having to re-enter the field positions. 

Sample input and output files, along with the field marking 
configuration entered to generate the output data, are shown 
in Figure 1. 

The program was compiled using Microsoft C version 7, the 
small memory model with a stack specification of /F 1000. □ 


< 

Figure 1 Sample data for fimport.exe 


Sample input file for FIMPORT.EXE: 

AUD PM0040 STARTED10225903041993 
AUDMASTERPLU ERR0R10225903041993 
AUOCTREE ERROR 1210225903041993 
AUDMASTERUPC ERR0R10225903041993 
AUDCTREE ERROR 1210225903041993 
AUDFDSW0RK ERROR: 10225903041993 
AUDCTREE ERROR 1210225903041993 
AUD PM0040 ENDED 10225903041993 


End-of-Field markers specified for the raw input above: 
AUD PM0040 STARTED10225903041993 

A AAA 


Output data generated from above input and field markings: 

"AUD"," PM0040 STARTED","102259","03041993" 

"AUD","MASTERPLU ERROR","102259","03041993" 

"AUD","CTREE ERROR 12","102259","03041993" 

"AUD","MASTERUPC ERROR","102259","03041993" 

"AUD","CTREE ERROR 12","102259","03041993" 

"AUD"."FDSWORK ERROR: ","102259","03041993" 

"AUD","CTREE ERROR 12","102259","03041993" 

"AUD"," PM0040 ENDED ","102259","03041993" 


.IMP field definition file automatically created: 

sample.inp 
0 3 
3 15 
18 6 
24 8 
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relationships and then generate the C++ source code with the push of a button. 
Integrated DDF file editing, configurable code generation, derived class creation, 
and more. $229. Bundle price: Btrv++ and Btrvgen++ for only $349. 
VBtrv\C++: Combine DDFGEN, the Control Pack and Btrv++ for only $249. Add 
the source to Btrv++ for a total of $349. Add Btrvgen++ for only $349. Add both the 
source code to Btrv++ and Btrvgen++ for a total of $449. 

VBtrv: Combine DDFGEN, the Control Pack and and a function call library 
specially built for Visual Basic and source code compatible with our VBtrv for DOS 
product. Only $199. Add our VBtrv for DOS product for a total of $299. 

Classic Software, Inc. 313-677-0732 (Voice/FAX) 

3542 Pheasant Run Circle Ste. 8, Ann Arbor Ml 48108 


□ Request 143 on Reader Service Card □ 


Sax Comm Objects lets you 
write Windows comm, apps 
in no time * 

With Sax Comm Objects, you can save time and add value to 
your Windows applications by plugging in high-level, 
royalty-free comm, objects. 

• X,Y,ZModem, Kermit, CompuServe B+ File transfers 

100% in the background with optional status dialog box 

• Color Ansi, VT52, VT100, TTY emulations with 
capturing, scroll back, and mouse selection. 

• Modem database with over 100 modems, extensive 
modem control functions 

• Common Dialogs for Communications for dial status, port 
settings, dial directory, etc... 

Don't waste another minute with cumbersome, old-fashioned 
programming when Sax Comm Objects can be yours for only 
$299. Call 1-800-MIKESAX for more information. 

• well... ok, maybe five minutes. 


Supported Platforms 
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Visual C/C++ 

Borland C/C++ 

Microsoft 

DLL ot MFC 

DLL or OWL 

Visual Basic 

w 


w 

FoxPro lot Windows 

Paradox lot 
Windows 

Microsoft Access 



Copyright © J993. Sax Software For Visual Basic version of Comm 
Objects, call Crescent Sottwarc at (203 1 4385300 


SOFTWARE 


1-800-MIKESAX 

Fax: 202-785-3607 Visa/MC welcome 
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C CODE FOR THE PC 

source code, of course 

X/DOS and Xt/DOS (Xlib with X client and Xt toolkit for DOS; port X code to DOS; Xt/DOS requires X/DOS and 32-bit compiler) . . each $345 
ZIP Image Processor & Victor Image Library Version 2.2 (brightness, contrast, meree images, TlFF/GIF/PCX/bin, HP ScanJet support) . . $290 

The Snooper (Ethernet protocol analyzer for Novell Net wire and LAN Manager Networks; capture packets; real-time display).$275 

NEW! Embedded BIOS (full-featured, real-time input/output system; PC, XT; AT; for example, 80186 with 8259 interrupt controller).$260 

TirtooTLX (Release 3.0; HP, PS, dot drivers; CM fonts; liTgX; MetaFont).$250 

Rogue Wave tools.h++ or math.h++ Class Library (extensive docs).each $240 

C/C+ + Libraries by Code Farms (persistent C structures, ER models, dynamic arrays, database functions, Jolt Award winner).$170 

c-p slib (PostScript generation library for C programs; includes complete graphics, font, rotation & paragraph support).$170 

TE Editor Developer’s Kit Ver. 3.0 (full screen editor, undo command, multiple windows; with Word Processing $230).$155 

Minix Operating System (Version 1.5; Unix-like operating system, includes manual; 3.5” diskettes only).$150 

Delorie GCC for MS-DOS (Version 2.2.2; includes C++, assembler, DOS extender, 387 emulation; complete source code and makefiles) . . $150 

Ibrow (Version 4.1; programmer’s Windows-based editor; large files, help, undo/redo, drag-n-drop, function & type tags).$135 

Booter Tbolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$120 

Lisp for DOS (Kyoto Common Lisp and CLISP; KCL includes Lisp-to-C translator for building mixed Lisp/C programs) .$100 

386BSD Version 0.1 & LINUX Version 0.96 (two Unix clones for Intel 386).$100 

PC/IP (CMU/MIT TCP/IP for PCs; Crynwr drivers, NFS server, Bdale mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . . $100 

Demacs (complete GNU Emacs for DOS; needs djgcc to build; based on 18.55).$100 

NEW! DA (disassembler for Microsoft’s New Executable (NE) binary files including Windows .exe, .drv, .dll, and .fit).$95 

Script Interpreter (a command script interoreter for DOS-based systems; C-like script language; lots of features).$90 

Hort+ + Power (C+ + Class Library for Borland’s Paradox Engine).$80 

NEW! CELP 3.2c (Federal Standard 1016 Code Excited Linear Predictive voice sampling and encoding; voiceover 4.8kbps).$80 

CPPCOMM (Version 3.0; C+ + serial communications class library for DOS, Windows, OS/2, and NT; includes X/Y/Zmodem) .$75 

ET Neural Net (hack error propagation and Kohonen; specify DOS text, DOS VGS, or Windows).$75 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify C or C-|—(-).$65 

Smalltalk for DOS (port of GNU Smalltalk using djgcc).$60 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$60 

Coder’s Prolog (Version 3.0; inference engine for use with C programs).$60 

PCCTS (Purdue Compiler Construction Tool Set; ported to Microsoft C; like YACC and LEX together with lots of additional features) . . . $60 

MEM.WING (global memory manager for Windows, supports standard C memory allocation calls to ’’wing” your old C code into Windows) . $55 

Container Lite V 1.82 (C+ + & FLC wrapper emulators; portable, persistent containers of arbitrary data including pointers).$50 

BigFloat (arbitrary precision floating point arithmetic and functions; includes BCD conversion).$50 

EZCalc (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories).$50 

Moby Crypto (Volume 1: DES, Lucifer, SRNG, ARNG; Volume 2 PGP, RSA, MD4, SHA; both volumes $75; not for export).each $50 

OBJASM (convert .obi files to .asm files; output is MASM compatible) .$50 

CLIPS Version 5.1 (rule-based expert system generator; advanced manuals available at additional cost).$50 

NIH Class Library & Book (basic C++ classes & Data Abstraction and Object-Oriented Programming m C+ + in softback by Keith Gorien) . $50 

Editor Pack (20 public domain editors; micromacs 3.12, Stevie, Elvis, Moke, mg2a, DTE, Jove, Origami, CE & GRIEF).$50 

MicroC C Compiler (retargetable C compiler/optimizer, lots of docs, very portable, 8086 tables included; tables for 7 extra epu’s $50) .... $50 

TOUR (beautiful traveling salesman problem solver, finds minimum length paths quickly, includes graphics & plotting programs) .$40 

DES Encryption & Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; not for export).$40 

Database Pack (9 databases - simple to complex: isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

COP (poor man’s C++; C macro package which implements C+ + in C) .$35 

RXC & EGREP Version 20 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Bison & BYACC (YACC workalike parser generators; documentation; includes C and C++ grammars) .$35 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

Updated! Alloc-GC (a garbage-collecting memoiy allocation libraiy).$30 

REGX Plus (Version 3.0, search and replace string manipulation routines based on compiled regular expressions).$30 

GNU Awk & Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression & expansion programs; now includes portable ZIP).$30 

Exceptions for C (Ada-like exception handling for C programs; exceptions for any block; exceptions can be reraised).$30 

OEmacs (full GNU Emacs for DOS and Windows DOS box; C+ + support, etags++, lots of .el files) .$25 

UUPC Pack (UUCP for the PQ UUPC Version 1.11V, smail & snews) .$25 

PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

FLEX (fast lexical analyzer generator; new, improved LEX; BSD Version 23.6 with docs) .$25 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better, Keeps track of software development).$20 

Simple Socket Library (Unix, VMS and MS-DOS; sits on TCP/IP stack).$20 

Bywater BASIC Version 1.10 (complete BASIC interpreter and interactive programming environment).$20 

Data 

Moby Thesaurus (25K root words, 1.2M synonyms).$350 

Moby Part-of-Speech (200,000 words and phrases described by prioritized part(s)-of-speech).$120 

Moby Words (500,000 words & phrases, 9,000 stars, 15,000 names).$80 

Moty Shakespeare (plays, sonnets, etc. ... every last word).$60 

Dictionary Word List (234,932 words in alphabetical order).$60 

Roget’s 1911 Thesaurus..$40 

U. S. Cities (names & longitude/latitude of 32,000 U.S. cities and 6,000 state boundary points).$35 

CIA World Bank II Database (13MB of maps, 5.7M vectors; coastlines, rivers, political boundaries; Africa, Asia, Europe, N. & S. America) $35 

The World Digitized (100,000 longitude/latitude of world country boundaries).$30 

Lots 'O Words (160,086 German, 178,430 Dutch, 61,843 Norwegian, 60,453 Italian, 138,257 French, 53,142 English) .$30 

CD-ROMs 

FontMaster Library (soft fonts for HP and HP compatible laser printers, 36 different type faces; 5,200 bit mapped fonts; 300MB).$70 

NE W! Prime Time Freeware for Unix (Volume 2, No. 2, July, 1993; over 3.5GB of Unix C code).$60 

Prime Time Freeware (Volume 2, No. 1, January, 1993; over 1GB of Unix C code; Icot, NetLib, UK TeX archive).$60 

Linux/GNU/X by Yggdrasil Computing (beta release; run from the CD; TCP/IP & NFS; drivers; MPEG; SCSI support; lots more).$60 

Walnut Creek Ltbris Britannia (over 600MB of the best of British boards; not all source included!..$55 

Walnut Creek C User’s Group (Volumes 100 to 364).$40 

Updated! InfoMagic Unix (three public domain Unix systems: 386BSD (version 0.1), Linux (version 0.99.10), and NetBSD).$40 

Updated! InfoMagic Source Code (Berkeley Net/2, MACH, GNU, Interviews, X, Andrew, XFree, Demacs & Winemacs, djgpp, Modula-3, etc.) . . . $40 

NEW! Austin Code Works Internet Wbrrior #1 (PC Internet tools: Gopher, Wbis, Eudora, ph, Nupop, Thimpet, TCP/IRFAQs, drivers, docs) . . . $35 

Wblnut Creek X11R5 and GNU (X11R5 with contributed and comp.sourcesx, over 120 GNU programs, complete C source).$35 

Whlnut Creek Usenet and Simtel Unix-C (600MB).$35 

Walnut Creek Simtel 20 MSDOS Archive (C source code but lots of other stuff too).$20 

Sprite Network Operating System (source code & documentation of Ousterhout’s Sprite O/S; Sun and DECStation boot images).$20 

The Austin Code Works Voice: (512) 258-0785 

11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1842 

Austin, Texas 78750-3587 USA E-mail: info@acw.com 

Free surface shipping for cash in advance For delivery in Texas add 7% MasterCard/VISA 
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A Windows Bug Unearthed; 
Using WDEB 386 


Q [Editor's note: The following question was originally posed on BIX, not ad¬ 
dressed to Paul, but it was too cute to pass up so we are running it with Tony’s 
permission.] 

;E3= Borland C++ v3.1 

mSBm Microsoft C/C++ V7.0a 

Zortech C++ v3.1 
Visual C++ v 1.0 


I have an app that talks to an app, the two to tango together. 

I FindWindow() the friend, 

get the child to the end 

‘til the handle of the edit's on tether. 

Set the dialog text 
do SetFocus() and next, 
nothing shows up on the Edit. 

The same trick, when you're tryin' 

with a static, is fine - 

what's so special about the Edit? 

The handles have been checked with Winsight, etc. All is well, yet the edit con¬ 
trol does not show the sent text. I foggily remember something about a particular 
sequence having to be done to have it show up. 

Tony Milosz 


Paul Bonneau 


Send questions to Paul via Internet 
as paul@rdpub.com-, 
from CompuServe: 
>INTERNET:paul@rdpub.com-, 
or in care of this magazine at: 

1601 W. 23rd St., Suite 200 
Lawrence, KS 66046-2743. 


A The problem restated in prose is this: SetUindowText() and SetDlgltemTextf) 
do not seem to work when applied to an edit control owned by another ap¬ 
plication. I checked this out with Soft-ICE/W and it is definitely a bug in Windows. 
Both SetUindowText() and SetDlgltemTextf) call a core routine to do the work. To 
find out if the window whose text is to be set belongs to another application, this 
routine compares the task queue of the target window with the task queue of the 
current application. Depending on the outcome, the routine then takes one of two 
completely different execution paths. If the window does belong to the current task, 
the call works as expected. 


Paul Bonneau is a Software Design Engineer at a major software firm. He was a 
developer of HyperChem, a molecular modeling system marketed by Autodesk. 
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FOR ALL EUROPEAN 
SOFTWARE VENDORS 

In order to serve our 
European advertising 
customers better, 
Windows/DOS 
Developer’s Journal 
now has a 
European Advertising 
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located in Germany. 

Now it is even easier 
for you to reach 
over 22,000 
experienced Windows 
programmers worldwide 
with an advertisement in 

Windows/DOS 
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Brian Osborn 
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D-24159 Kiel 
Germany 

Phone 
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Wouldn’t it 
be nice to make 
your product 
known around 
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If the window belongs to another 
task., the code allocates some local 
memory in a private USER heap to hold 
the text, and places the handle at offset 
0x32 in the target window's internal 
PND structure (see Schulman et al., Un¬ 
documented Windows [Addison-Wesley, 
1992], or the June, 1992 Windows Q&A 
for a description of this undocumented 
structure). If the offset already contains 
a handle, that handle is freed first This 
offset is used to hold the title text of a 
window, which is completely different 
from an edit’s text buffer. I do not 
know why the two paths of execution 
exist. Perhaps it is some kind of op¬ 
timization to avoid an intertask Send- 
Message(). The first path of execution 
does not call SendMessage(), but calls 
the window's window procedure direct¬ 
ly. 

Another weird feature of the inter¬ 
task SetPindowTextf) is that it does 
not tell the target window to redraw it¬ 
self after its title buffer has been 
replaced. 1 verified this by creating a 
test application that creates a modeless 
dialog (see Figure 1) that possesses an 
edit control and a static text. After 
creating the dialog window, the test ap¬ 
plication enumerates all top-level win¬ 
dows, looking for windows possessing 
the same module handle; such win¬ 
dows must be the dialogs of other in¬ 
stances of the test application. When 
one is found, the test application uses 
SetDlgItemText() to set both the text 
of the edit and the static control to an 
ASCII representation of the task’s in¬ 
stance handle. After the second in¬ 
stance of the test application is run, you 
must drag the first instance offscreen to 
see the static text update its title. The 
edit text remains unchanged. The test 
application’s C source is in testbug.c 
(Listing 1), the dialog resource is in 
testbug.rc (Listing 2), and testbug.h 
(Listing 3) contains some dialog con¬ 
stants used by the first two files. 

Luckily, the problem is easy to work 
around. You can deliver a UM_SETTEXT 
message to the window with either 
PostMessagef) or SendMessage(). Be 
careful using PostMessage() if the buff¬ 
er containing the string resides on the 
stack, since the buffer may be invalid 
by the time the message is processed 
by the target window. To summarize: 


Windows still has at least one bug; 
you proved it —you went and found it! 
No need to sweep it under the rug, 
just weave the rug around it 

Q I have the following problem: 

sometimes, after 1 have started 
the application I’m developing, Win¬ 
dows seems to hang. The mouse 
pointer moves around the screen, but 
no window can get the focus, or be 
moved, and so on. It seems that my ap¬ 
plication is in a loop. However, my ap¬ 
plication is simply a client user interface 
for an Ultrix or VMS server, and I cannot 
figure out where in my code it can 
loop, or what is happening. I suspect 
that the problem is in the interaction 
with the networking software, whose 
lower layers run as a TSR in real mode. 
The only way to regain control is to 
press the Ctrl-Alt-Del keys. Windows 
goes into full screen mode, telling me 
that ’’xxx.exe has stopped responding to 
the system,” or "The system has be¬ 
come busy or unstable,” etc. Usually, 
my next move is to reboot. 

My question is: Is it possible in that 
situation to dump the state (number of 
tasks, current task, its stack, its program 
counter, and any other useful informa¬ 
tion) of the system? Can the Ctrl-Alt- 
Del sequence be hooked by the user? 
Could the Soft-ICE/W debugger by Nu- 
Mega Technologies be useful (I do not 
have it; I use MS CodeView)? 

Stefano Corgnati 
corgnati@yapp.enet.dec.com 

A As you are discovering, CodeView 
is useful for application-level 
debugging, but when it comes to low- 
level problems, such as Windows/DOS 
communication, it is not much help. 
However, assuming you have the SDK, 
you already possess WDEB386, a low- 
level debugger more than up to the 
task. WDEB386 provides very powerful 
low-level debugging support, but 
without the niceties of the CodeView 
interface. 

You interact with WDEB386 using a 
dumb terminal connected to your PC 
through one of the serial ports. You can 
break into the debugger at any time by 
pressing Ctrl-C on the terminal’s key¬ 
board (unless, of course your machine is 
truly hung). 
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You can examine the list of running 
Windows tasks with the “.dq” com¬ 
mand. This displays a list of those tasks 
possessing a task queue (every task 
with at least one window also posses¬ 
ses a task queue) and highlights the ac¬ 
tive task with an asterisk. Figure 2 
shows some sample output. It indicates 
that ProgMan is the active task. 

The TDB field provides the selector 
for the task's task data base. The hQ 
field contains the selector for the task’s 
event queue. Undocumented Windows 
describes both of these data structures. 
The SS:SP field is the stack pointer the 
last time the task was switched away 
to another Windows task. The nevt 
field shows the number of events in the 
task's queue. The prty field contains 
the task’s priority, normally 0 (see 
pages 405 through 407 of Matt Pietrek, 
Windows Internals [Addison Wesley: 
1993] for a discussion of task priority). 
The next three fields are a bit of a 
mystery. Microsoft’s documentation has 
this to say: “intemal-messaging-informa- 
tion: Specifies information about inter¬ 
nal messages.” However, they are dis¬ 
cussed on page 446 of Windows Inter¬ 
nals. Each field is a bitmap of flags. The 
"wake bits” flags indicate which types 
of messages are available. The flags are 
the same as the QS_ flags returned by 
GetQueueStatusf). The ’’wake mask" 
indicates which types of messages the 
application is waiting for, and the 
change bits indicate which of the wake 
bits have changed since the last time 
the queue status was checked. 

You can use the ”.dg” command to 
dump the contents of the Windows 
global heap. Figure 3 contains some of 
the lines emitted when I executed the 
command. Unfortunately, the SDK 
documentation is simply wrong in its 
description of the output from this 
command. According to the documenta¬ 
tion, the first field gives the physical ad¬ 
dress of the segment, but this is only 
true in standard mode, where the linear 
and physical addresses are the same. 
The field actually shows the linear ad¬ 
dress in either mode. The next field, 
arena, is missing from the documenta¬ 
tion. On an 80386 or better, it is the of¬ 
fset of the segment’s arena header in 
the master global array (see Undocu¬ 
mented Windows for a description of 


the internals of the Windows global 
heap). 

The size field shows the size of the 
segment in bytes. You wouldn’t think 
the documentation could get a simple 
field like this wrong, but it does. The 
description says that in standard mode 
the field gives the size in 16-byte para¬ 
graphs. This is certainly not true of my 
80486 in standard mode. It may be true 
of an 80286 in standard mode, since the 
80286 version of the kernel is used in 
that case, but I have my doubts. The 
type field contains a description of the 
segment’s usage. Possible values in¬ 
clude “BURGERMASTER,” “PRIV,” “DATA,” 
“SENTINEL," “RSRC,” “CODE,” “FREE.” Table 
1 summarizes these values. 

The handle field shows the handle 
and its flags, e.g. (17BE, 1 ,L1 ,P1). The 
documentation says that if the handle 
is missing, then the segment is fixed. 
This is not true. As for the flags, the 
documentation claims that a “D” means 
the segment is moveable and discar¬ 
dable, and an “L” means the segment is 
locked. It further says that if an “L" ap¬ 
pears, it is followed by the lock count. 
This is partially correct. This is what I 
think the numbers really mean. The 
first number after the handle is the 
number of selectors allocated to ad¬ 
dress the segment (may be greater 
than 1 for segments larger than 64Kb). 
Next, if an “L” appears, it is as the 
documentation says — the segment is 
locked. Next, if a “P” appears, the seg¬ 
ment is page locked, and the next 
number is the page lock count. I should 
point out that the only segments that 
get locked these days are discardable 
ones. Locking prevents the kernel from 
discarding the segment. Locking any 
other segment has no effect and does 
not increase the lock count. This seems 
to imply that if an “L" is present, then 
the segment is normally discardable. 

The remaining field in the documen¬ 
tation is the LRU chain (the debugger 
titles it “LRU Links”). If the field contains 
a pair of numbers, these indicate the 
previous and next segments in a linked 
list of discardable segments. Windows 
maintains an LRU list to determine 
which segment to discard when 
memory needs to be freed to satisfy an 
allocation request The last field shown 
by the debugger is not mentioned in 
the documentation but is fairly 


TurboT^X 

Typesetting Software 



Microsoft with c source 
windows ofonn 

COMPATIBLE "’OUU 


The TftK typesetting 
system implemented in 
portable C for MS-DOS, 
Windows, and Berkeley 
and System V Unix. 

T he WORLDWIDE STANDARD for beautiful 
publishing in science and engineering is 
TgX, a set of programs which produce mathe¬ 
matics and text in impeccable clarity and style. 

TuiboTgX 3.1 is a best-selling, industrial- 
strength implementation of TgX for the most 
popular operating systems. Included are 
plain TgX, LaTgX, METAFONT, AmS-T^X and 
AmS-LaTj3(, the Computer Modern fonts, 
WYSIWYG previewer, drivers for HP Laser¬ 
Jet/DeskJet, PostScript, and Epson LQ and FX 
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User's Guide, and free technical support. The 
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With the source code option, you can recon¬ 
figure the system for novel features, embed 
typesetting in your vertical application, port 
to a new platform, update to a new OS revi¬ 
sion, or just study a major product in detail 
(including the WEB system in C, our Pascal- 
to-C translator, Windows interface, and DOS 
virtual memory simulator). Source requires 
Microsoft C, Watcom C 8.0, or Borland C++ 2.0 
for MS-DOS; Microsoft C for Windows, or a 
32-bit ANSI or K&R C compiler for UNIX. 

Ordering is easy by phone, FAX, or 
mail, and delivery is fast! Terms: 
check with order (free USA ground 
shipping), VISA, Mastercard, or 
COD. Net 30 to well-rated firms 
and public agencies. International 
orders welcome. 

Free 70-page Buyer's Guide by mail. 



The Kinch Computer Company 


Publishers of TurboTeX 
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Ithaca, New York 14850 USA 
Telephone (607) 273-0222 
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Listing 1 textbug.c - Main dialog to demonstrate SetWindowTextQ bug 

fit**************************************************** J 

hwnd = GetWindow(hwnd, GW HWNDNEXT)) 

1* textbug.c */ 

if (GetInstanceModule(GetWindowInstance(hwnd)) 

/* — Set the text of another application's edit */ 

== hmod) 

/* control in a dialog. */ 

( 

/* cc -DSTRICT textbug.c */ 

SetDlgItemText(hwnd, didEdit, szlnstance); 

j ***************************************************** j 

SetDlgItemText(hwnd, didStatic, szlnstance); 

linclude <windows.h> 

i 

linclude <windowsx.h> 


linclude "textbug.h" 

while (GetMessage(&msg, NULL, 0, 0)) 

BOOL CALLBACK export 

if (UsDialogMessage(hwndDlg, &msg)) 

{ 

FDlgProc(HWND, UINT, WPARAM, LPARAM); 

TranslateMessage(&msg); 

lifdef B0RLANDC 

DispatchMessage(&msg); 

} 

Ipragma argsused 

return msg.wParam; 

lendif 

i 

int PASCAL WinMainfHINSTANCE hins, HINSTANCE hinsPrev, 


LPSTR lsz, int wShow) 

lifdef B0RLANDC 

j ***************************************************** j 

Ipragma argsused 

/* -- Entry point. */ 

lendif 

j ***************************************************** j 

BOOL CALLBACK export 

i 

FDlgProc(HWND hwnd, UINT wm, WPARAM wParam, 

char szlnstance[10] ; 

LPARAM IParam) 

HMODULE hmod; 

j ***************************************************** j 

HWND hwnd, hwndDlg; 

/* -- Dialog procedure. */ 

MSG msg; 

y************************************************ ***** ^ 

if ((hwndDlg = CreateDialog(hins, 

l 

switch (wm) 

MAKEINTRESOURCE(dlgDemo), NULL, FDlgProc)) 

i 

== NULL) 

default: 

return 0; 

break; 

/* Set the text of all other siblings' edit */ 

case WM INITDIAL0G: 

/* control with our instance handle. */ 

return TRUE; 

wsprintf(szlnstance, "%x", hins); 


hmod = GetlnstanceModule(hins) ; 

case WM COMMAND: 

for (hwnd = GetWindow(hwndDlg, GW HWNDFIRST); 

switch (wParam) 

hwnd != NULL; 

i 
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bucks for a compiler and programmer's 
toolkit only to discover the real cost of 
programming: the learning curve. 
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straightforward. Seg\Rsrc gives either the module segment 
number for a code segment, or the resource number and type 
for a resource. 

As for DOS memory, I assume your TSR is started before 
Windows. In that case it is running in the system VM (and for 
that matter, copied into each and every subsequent DOS VM 
started). It therefore shares its memory with all of the Win¬ 
dows programs running in the system VM. Each VM accesses 
memory from its own local descriptor table, and the system 
VM is no exception. If you break into the debugger when the 
system VM is active (i.e., a DOS box does not have the execu¬ 
tion focus), then the first megabyte of linear memory (which is 
the same as physical memory at this point) can be examined 
using the linear address operator, “%”. For example, I can 
enter “db %f0000”, (real-mode address f000:0000) to see the 
BIOS copyright message. 

The hardest part of your question is determining the in¬ 
struction pointer. I'm sure there is a good explanation for the 
voodoo I am about to show you, but I have never bothered to 
trace through the bowels of the kernel to find out why it 
works. All I know is it's invaluable when debugging, and has 
never failed me. When you break into the debugger in en¬ 
hanced mode with Ctrl-C, you will be deep inside the virtual 
machine manager. This means 32-bit, ring 0 code, no symbols 
(unless you have purchased the DDK and installed the debug 
version of win386.exe and are using win386.sym), and no idea 
whatsoever of where your program was when you inter¬ 
rupted it. But the key is that it was interrupted, so you can 
get back to it. 

In enhanced mode, continue execution to address 3B:220, 
using the command "g 3B:220”. You should see an I NT 30h 
instruction. Now use the “t” command to trace into the in¬ 
struction. Don’t substitute the “p” command, since it will never 
return. Voila, you are now back inside your program (assum¬ 
ing it was the one running when you hit Ctrl-C). This magic 
works in either the retail or the debug version of Windows 
3.1. Standard mode is equally arcane. After you break into the 
debugger, go to address 53:14FB using "g#53:14FB’’ (the “#" 
specifies the protected-mode address). You should see an 
IRET instruction. Once again the “t” command will take you to 
where you where executing from. 

Both the above magic addresses are in segments in the 
global descriptor table, so are accessible from any VM. But 


Listing 1 continued 


default: 

break; 

case IDOK: 
case IDCANCEL: 

DestroyWindow(hwnd); 
return TRUE; 

i 

break; 

case WM_DESTROY: 

PostQuitMessage(O); 
break; 

} 


return FALSE; 
} 

/* End of File */ 


there is a catch. Trying to break into WDEB386 from a DOS box 
in standard mode is not a good idea. It cold reboots my 
machine. Your mileage may vary. 

Nu-Mega’s Soft-ICE/W debugger is also a powerful low-level 
debugger with a nicer user interface than WDEB386, although 
not as rich as CodeView's. It has a better range of breakpoint 
commands than does WDEB386 (for example, you can set a 


Listing 2 

textbug.c 

textbug. rc - 

Resource definitions for 

linclude <windows 

h> 



linclude "textbug 

h" 



dlgDemo DIALOG 6, 

18, 96, 48 



STYLE DS MODALFRAME | WS POPUP | WS 

VISIBLE | 

WS CAPTION 1 WS 

SYSMENU 



CAPTION "SetDlgltemText Test" 



FONT 8, "MS Sans 

Serif" 



BEGIN 




LTEXT 

"Static Text", 

didStatic, 


2, 2, 92, 12 



EDITTEXT 

didEdit, 2, 16, 

92, 

12, 


ES AUTOHSCROLL 



DEFPUSHBUTTON 

"&OK", IDOK, 2, 

32, 

92, 14 

END 





Listing 3 

textbug. h - Header file for textbug.exe 

Idefine dlgDemo 

1000 

#define didEdit 

1001 

Idefine didStatic 

1002 

/* End of File */ 



How Can You Catch Nasty 
Race Conditions That Take All 
Night to Happen Without 
Waiting All Night? 

CodeProbe. M 


The new high-performance software analyzer that 
captures, time-stamps, and records software and hardware 
interrupts, DOS calls, BIOS interrupts, and user-defined 
events in real-time for analysis of race conditions, 
interrupt activity, and service times. CodeProbe gives you 
the hard facts you need to fix the big one that stands 
between system test and shipping your product. 
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Figure 1. Detailed timestamping of C library fread() function call. 

If CodeProbe can break-down a library function call into 
its components (above), imagine how you'll see context 
switches, device interrupts, and other asynchronous code. 
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Figure 1 Demonstrating the SetWindowTextQ bug 


hardware breakpoint on a memory range in Soft-ICE/W but 
not in WDEB386) but lacks the very useful ability to execute a 
user-specified command when a breakpoint is hit. Soft-ICE/W 
can only be used in enhanced mode, but WDEB386 can be 
used in either standard or enhanced mode. You can contact 
Nu-Mega at P.0. Box 7780, Nashua, NH 03060-7780 U.S.A., 
phone (603) 889-2368, fax (603) 889-1135. 

Q Can a DOS application running under enhanced mode 
determine whether it is running windowed or full 
screen? Reliably? The DDK and Undocumented Windows seem 
to be mum on the subject, unless I’m missing something. In 
case you’re wondering why I need the info, it’s for a DOS 
mouse tutorial that wants to skip certain lessons (cursor 

I Does your company 
provide tools, products, 
or services for advanced 
Windows programmers? 
Then reach over 22,000 
serious programmers in: 

Windows/DOS 

O DEVELOPER'S JOURNAL 

Call 913 - 841-1631 today for 

information about 
advertising opportunities in 
Windows/DOS Developer’s Journal. 

Advanced. Serious. 
Technical. 


I Brian Osborn - Continental Europe. 

+49 431-396895 

I Ed - East I Donna - Midwest I Edwin - West 
913-841 -1622 I 913-841 -6733 I 913-841 -1626 


growth, sensitivity, acceleration) if we’re mousing-in-windows 
(and therefore not plotting our own cursor). 

John Jurewicz 
CIS: 76004,2311 

A Since you own the DDK, you may be in luck. There is a 
VxD in the samples directory on the CD-ROM that does 
exactly what you want. Its name is VWFD, and in case you 
don’t have a CD-ROM drive, you can download VUFD.ZIP from 
library 17 of the Microsoft SDK library on CompuServe. This 
VxD uses an interesting technique of hooking out the virtual 
display device's VDD_Set_VMType service to trap all calls to 
set a DOS VM to windowed or full screen. The intercepted flag 
is stored in a private control block allocated by VWFD in each 
VM. The VxD accepts a VM ID number, finds the corresponding 
VM handle if it exists, and returns the VM’s windowing status 
obtained from the control block data. 


Reader Letter 

Hi I I just read your Multi-Font Edit Controls in Windows/DOS 
Developers Journal. It seems to me that your reply to Cyril 
Chapman, although demonstrating considerable technical 
wizardry, doesn’t really communicate the kind of clean and 
straightforward approach that is the hallmark of the ex¬ 
perienced developer. At a minimum, it would be worthwhile 
considering what options are available. 

Dr. (?) Chapman needs to display mixed text and symbols 
for a scientific program. He may also want to allow the user 
to enter and/or edit this text stream. 

Certainly the simplest solution is to create or find a font 
which has all the characters he needs. There are a number of 
utilities which would let him build such a font, including even 
Fontedit, since a single bitmap font would probably be per¬ 
fectly adequate for his needs. I’m not involved with scientific 
computing, but there are probably public domain fonts already 


Figure 2 Sample output from WDEB386's .dq 
command 


Chng Wake Wake 

TDB SS:SP nevt prty hQ Bits Bits Mask Module 

1397 1357:1D5A 0000 0000 137F C000 4000 007F WIN0LDAP 

*0647 174F:1FFA 0000 0000 07CF C000 4000 007F PR0GMAN 
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available which meet his needs. As I understand, the entire 
purpose of your routines is to create a synthetic font. 

The second option is that direct editing is not required. The 
obvious solution in that case is not to use a control, but simp¬ 
ly paint the text on the screen. 

A third option, assuming editing is required, is to write a 
very simple word processor directly on a window. If vertical 
and horizontal scrolling are not required, it doesn't take much 
code to handle caret placement, selection, insert, and over¬ 
type. 

It becomes clear that understanding the requirements is 
(as always) the key to finding the “right" solution, and I’m sure 
further options would present themselves based on seeing 
what is really desired. 

I enjoy your column, but just felt the need to put my two 
cents' worth in. I've always found KISS to be the key to suc¬ 
cess. 

Wahhab Baldwin 
wahhabb@microsoft.com 


Response 

Thanks for the comments, people rarely take the time to 
give me feedback. I actually first thought about creating a cus¬ 
tom font, but abandoned the idea for the following reasons: 

• Creating a new font using the SDK tools (namely FontEdit) 
is non-trivial (although as you point out, there may already 
be PD bitmap fonts available). 

• Creating a new font is not as general as mixing glyphs from 
two (or more) fonts on the fly. 

• Creating a new font by itself is not enough. There must 
also be code to allow the user to access the non-ASCII 
characters. This means modifying the edit control's be¬ 
havior, probably through subclassing. But the amount of 
work to both create a new font and write a subclass pro¬ 
cedure is substantial, and probably more than was in¬ 
volved in my solution. 

I don’t think you would have a very nice user interface if 
the user could not do direct editing. At any rate, I assumed 
that was what Mr. Chapman was asking for. One of the 
problems in a forum such as this is trying to intuit exactly 
what the reader is asking for, given a short letter. Some 
guesswork is usually required on my part. Also, I tend to 
answer questions that I think will have general reader appeal. 
My answer to Cyril Chapman’s question is a reusable DLL that 
may be useful for other people who must resort to hooking 
out Windows functions in other situations. 

As for the simple word processor, once again the problem 
is trying to guess what is really wanted. I tend to provide a 
general answer when there is some ambiguity in the ques¬ 
tion. In this case, a multiline edit is more general than a 
simple single line word processor. 

I respect your opinion, though, even if we disagree. And 
once again, thanks for the feedback. □ 


Table 1 Some segment types reported by 

WDEB386's .dg command 

Type 

Meaning 

BURGERMASTER 

Master global table. Contains global heap 
header information, and per-segment 
information. 

PRIV 

Private data. This may be a 

GlobalAllocO'ed segment, or a task data 
base. 

DATA 

A data segment. 

SENTINEL 

Special segments placed at the 
beginning and end of the heap. 

RSRC 

Resource segment. 

CODE 

Code segment. 


Figure 3 .dg command output 


Address 

Arena 

Size Type Owner 

Handle LRU Links 


Seg|Rsrc 

294C0: 

80 

Ob SENTINEL 

FFFFFFFF, 

4860 

294C0: 

CO 

CC80b CODE KERNEL 

(0117,1,PI) 

1 

36140: 

1FC0 

40b PRIV GDI 

(17BE,1,LI,PI) 


36180: 

2040 

7C0b CODE MMSYSTEM(15EF,1,P1) 

1 

36940: 

15 AO 

30b DATA MMSYSTEM(15AF,1,P1) 

9 


Pearl Software presents WinEmacs 


Emacs for Windows 


WinEmacs U a fully functional Windows 3.1. version of the 
industry standard program editor Gnu Emacs, version 19*3< 
WinEmacs is available with all Gnu Emacs source code. WinEmacs 
is fully compatible with the Lucid Inc. Unix version of Gnu Emacs. 


WinEmacs retains all the Emacs features you are used to: 


• Emacs Lisp Extension Language 

• Hypertext help, on-line manual 

• Line, block, character marks 

• Full undo and redo 

• Multiple buffers 

• Edits arbitrarily large files 

• Regular expression search/replace 

• Incremental search 

• Procedure tagging with completion for C, 
C++, Pascal, Lisp, and many others 


• Syntax expansion and indenting 

• Begin/end structure and brace 
matching 

• Word wrap and full justification 

• Runs programs from within editor 

• Configurable key bindings to arbitrary 
Emacs Lisp functions 

• Compatibility with UNIX emacs 
configuration tables 

• Mode line 

• Huge library of Emacs Lisp for other 
extensions 


Plus WinEmacs has these extended features: 


How you can obtain WinEmacs 


• Clipboard support 

• Scroll bars 

• DDE and OLE support 

• Binds any arbitrary combination of a 
key and key modifiers to Emacs Lisp 
code 


• Separate buffers in different windows 

• Menu and drop-down menu bar 

• Multiple font-size and type support 

• Cut and paste mouse support 

• Support for text and Binary files 

• Support for foreign keyboards 


You can try the demo version of WinEmacs without cost by contacting Pearl 
Software at pearl@netcom.com (e-mail) (510) 273-9795 (voice) or (510) 839-9820 
(fax). If you decide to use it, please register for technical support from Pearl ($199). 
This will entitle you to all upgrades (NT version soon!) for one year, and access to our 
BBS which posts bug fixes and full Emacs source code.. 

WE ALSO PROVIDE EMACS CONSULTING SERVICES 


Pearl Software, 320 Lenox Ave., Oakland, CA 94610 
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New Products 

Industry-Related News & Announcements 


POEM Offers High Compression 

POEM Hi-Res v2.0 is a compression system and 
developer’s kit for multimedia, archiving, or other imaging ap¬ 
plications that must be able to produce quality images from 
highly compressed bitmaps. To compress images, you can 
either use the supplied standalone Windows program or call 
DLL compression functions. Compression requires an FTC-li 
compression board and the package can compress images 
up to 11,000 by 11,000 by 24-bit color, producing quality im¬ 
ages even at compression ratios exceeding 150:1. To 
decompress images, you can call supplied DLL routines or 
link with C object libraries to decompress from DOS applica¬ 
tions. 

The package uses Fractal Transform Template (FIT) files, 
a technology that improves compression ratios and quality 
for groups of similar images, such as ID photos, maps, or 
fingerprints. FIF archiving is an optional secondary level of 


compression the package can perform on fractal files to 
reduce file size by 10 or 20 percent, at the cost of a slight in¬ 
crease in decompression time. 

POEM Hi-Res can compress images singly or in batch 
mode, and can create multiple compressed images in a 
range of file sizes during one compression run, saving time 
when you need to review image quality over a range of com¬ 
pression ratios. DOS and Windows applications can 
decompress images into 4, 8, or 24-bit color, with color map¬ 
ping and optional dithering for 4 and 8-bit output modes. 

You can decompress images at half scale, double scale, or 
the same scale as the original, and you can decompress to 
the screen, a memory buffer, or a Targa file. 

POEM Hi-Res v2.0 costs $3,995. For more information, con¬ 
tact Iterated Systems, Inc., 5550-A Peachtree Parkway, 
Norcross, GA 30092, (404) 840-0310; FAX (404) 840-0806. 


CSTI Releases C++ Libraries 

Communication Systems Technology, Inc (CSTI) has 
released three new C++ libraries: NETBIOS, PostOffice, and 
Scheduler. 

The NETBIOS class provides access to the NETBIOS API and 
includes support for NETBIOS Sessions, Datagrams, Broadcast, 
Name, error-handling routines, and wait and no-wait op¬ 
tions. Included examples show how to use this library with 
the company’s Scheduler library to process messages as 
they arrive without polling for completion. 

The PostOffice is a ZINC message switch that provides 
message-based communications between tasks. The mes¬ 
sages can be polled, or you can use the Scheduler library to 
designate a message-processing task to be activated upon 


New DLL Creates 3D Menus 

ProSoft has released a new DLL that lets you add fancy 
menus, including three-dimensional menus, to your applica¬ 
tion. ProMenu Library provides 50 functions and 22 mes¬ 
sages to support configurable and extendible menus with 
features not found in the standard Windows API. 

With ProMenu Library, you can create 2D and 3D menus 
that are transparent, hierarchical, and even non-rectangular. 
Your ProMenu menus can have different alignment styles: 
drop-down, drop-up, drop-right, drop-centered, and so on. 
Items within the menus can be non-rectangular, and the 
package provides configurable borders and margins, and 


receipt of a message. The class includes a method to dynami 
cally register mailbox tasks during program initialization. 

Scheduler is a ZINC task scheduler that simulates multi¬ 
tasking with corroborative scheduling. Tasks are schedules 
on an adjustable periodic basis and any task can change its 
periodic schedule time and entry point. You add, drop, block, 
unblock, and resume tasks. 

Any two of the libraries cost $79.95, or $99.95 for all 
three; the libraries include both source and object code. For 
more information, contact CSTI, 3800 Concorde Parkway, 
Suite 100, Chantilly, VA 22021, (703) 968-4956; FAX (703) 
968-7827. 


multiple styles of highlighting and alignment. The package 
supports indirect sub-item selection, drag selection and click 
selection of multiple items, default item selection, context- 
sensitive cursors, and configurable event mapping. 

ProMenu Library v 1.0 costs $ 150 through August 31, and 
$250 thereafter. A demonstration is available on Compu¬ 
Serve; download the file pmlib.zip from the WINSDK forum. 
For more information, contact Cain International Corpora¬ 
tion, ProSoft Division, 867 5 Ballantrae Drive, Colorado 
Springs, CO 80920, (800) 793-2246. 


Page 78 - Windows/DOS Developer's Journal 


September 1993 






































Toolkit Aids Multiport Development 

Developers Toolkit II is a package to help programmers 
create DOS and Windows 3.1 applications that exploit the 
Hostess i and Hostess 186 high-performance multiport serial 
controllers. The main component of the toolkit is a set of 
libraries that provide a high-level interface to serial com¬ 
munications. The package also includes on-board debugging 
capabilities resident in the controller’s firmware that let you 


debug source-level C programs on the serial controller using 
Borland’s Turbo Debugger. An external reset switch lets you 
reset the controller without having to boot your PC. 

Developers Toolkit II costs $695. For more information, 
contact Comtrol Corporation, P.O. Box 64750, St Paul, MN 
55164, (800) 926- 6876 or (612) 631-7654 ; FAX (612) 631- 
8117. 


Library Provides Device Driver Services 

Intelligent Tools Library is a new library that aids 
programmers who must access hardware devices in the Win¬ 
dows 3.x environment. The library offers a higher-level inter¬ 
face to hardware interrupt management, DMA hardware 
control, DPMI services, and VDS services. For example, a 
single function call handles the common task of installing an 
interrupt handler (saving the old interrupt handler, installing 
the new function, enabling the interrupt mask, and so on). 


The library functions are all written in assembly language 
and the library provides an alternate function call inteface 
for applications written in assembly language. 

Intelligent Tools Library costs $195 and is compatible 
with both real and 16-bit protected mode. For more informa¬ 
tion, contact InTool, Dept 9301b, P.O. Box 6334, Abilene, 
TX 79608, (817) 725-7455. 


Klondike Updates Windows Development Toolkit 


Diamond Toolkit is a set of tools for designing Windows 
applications. Its specialty is applications with dynamic win¬ 
dows and dialog boxes containing objects that can be 
added, moved, or modified. The Toolkit includes the 
Diamond library (a set of high-level C functions), Cockpit 
(which provides a workbench, code generator, and revision 
control), Helplt (hypertext-based help with style sheets, 
sound annotation, and zoom), Loadlt (an installation utility), 
and an extensive library of primitive objects. 

The new version adds memory management, using one 
function to access all available memory up to 16Mb. The 


user interface now offers spreadsheet and virtual list objects. 
The new version also includes multimedia support, text jus¬ 
tification, image scaling and halftoning, and MDi support 
using existing primitives. 

Diamond Toolkit vl.10 costs $395 for a single-user 
license, including complete source code and free customer 
support. It requires Microsoft C v7.0 or Borland C++ v3.1. For 
more information, contact Klondike Software Inc., 15 
Emery Court, Nepean, Ontario, Canada K2H 7W2, (613) 
726-6565; FAX (613) 820-8299. 


Develop Online, Concurrent Systems with AFC 


AFC v4.1 is the latest version of the Activation 
Framework toolset for Windows 3.1. This toolset is designed 
to reduce the time required to develop online, concurrent, 
event-driven systems. Applications include smart control sys¬ 
tems, automated test systems, diagnostic and warning 
sytems, real-time simulation and modeling, online data col¬ 
lection, and processing and display systems. The package in¬ 
cludes a real-time kernel, a 4GL rules-to-C language compiler, 
a realtime graphic user interface, and tools for automatic sys¬ 
tems integration. Separately priced packages support dis¬ 
tributed processing and automated test generation and 
evaluation. 

AFC v4.1 lets C/C++ programmers develop applications 
with multiple task objects executing as independent threads 
within each Windows process. These task objects are trig¬ 


PageAhead Releases ODBC Driver Kit 

PageAhead Software has released Simba ODBC Driver 
Tools for Windows, a package designed to reduce the large 
amount of work required to implement a typical ODBC 
driver. ODBC (Open Database Connectivity) is a Microsoft 
specification that provides a vendor-independent interface 
for applications to access vendor-specific databases. 

Since ODBC is essentially an SQL interface, creating an 
ODBC driver for a non-SQL database requires much of the 
work of implementing SQL. PageAhead's toolkit includes an 
SQL engine designed to handle much of this work. The 


gered by incoming messages and emit messages in 
response. Each task is written in a high-level, data-driven, 
rules language, called AFL, that controls when subroutines 
are called. An AFL rule can specify that a subroutine be 
called periodically or that it be called when a certain com¬ 
bination of data is received from other tasks. Values 
returned by these subroutines can be automatically sent in 
messages to other tasks. AFL task objects are compiled into 
C by AFC. 

AFC v4.1 costs $1495 and is also available for DOS and 
UNIX. For more information, contact The Real-Time Intel¬ 
ligent Systems Corporation, 30 Sever Street, Worcester, 
MA 01609, (508) 752-5567; FAX (508) 752-5491. 


toolkit also includes an interface library to handle much of 
the non-SQL aspects of implementing an ODBC driver, work 
required whether the target database supports SQL or not. 

PageAhead offers a complex pricing scheme for Simba 
ODBC Driver Tools for Windows that depends on factors such 
as whether you need the SQL engine, whether you are a cor¬ 
porate developer, and so on. For more information, contact 
PageAhead Software Corporation, Suite 301, 2125 
Western Avenue, Seattle, WA 98121, (206) 441-0340; FAX 
(206)441-9876. 
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Updated Configuration Manager Available on Alpha 


Softool Corporation has updated CCC/Manager for Win¬ 
dows, NT, and OS/2. CCC/Manager is a high-end software 
change and configuration management tool, and is now 
available for Windows NT on DEC’S Alpha AXP, a 64-bit RISC 
machine. 

CCC/Manager v2.1 offers many new features, starting 
with an object-oriented user interface; when users select an 
object (a package, configuration, or file, for example) the 
commands related to that object become available. 
CCC/Manager now operates modelessly, permitting simul¬ 
taneous operations —you don’t have to close the current 


dialog to go look at another one. The new version lets you 
create a structure within the CCC database that exactly 
matches your directory structure on the host, letting you 
check in an entire directory tree with a single command. 
Support for concurrent development has been added so 
code can be simultaneously updated by more than one user. 

CCC/Manager for Windows and CCC/Manager for Win¬ 
dows NT each cost $495 for a single unit; volume discounts 
are available. For more information, contact Softool Corpora¬ 
tion, 340 S. Kellogg Avenue, Goleta, CA 93117, (805) 683- 
5777; FAX (805) 683-4105. 


Software Adds Serial I/O to Any Application 


The Software Wedge lets you input data from any RS232 
instrument or serial device directly into any PC application 
without special hardware or custom programming. The 
Software Wedge captures data from your PC's serial port, cus¬ 
tom tailors it to your specifications, then transfers the data 
to any application you specify either by sending keystrokes 
to the application or by passing data via DDE. Data from your 
serial device appears to your application as if it were typed 
in on your keyboard, letting you use the package with 
programs such as Excel, Access, Foxpro, Lotus 123, Paradox, 
etc. 

The new Professional Windows version of the Software 
Wedge lets you connect data from a serial port to any Win¬ 
dows or OS/2 application. It provides data parsing and filter¬ 


ing capabilities, and formatting functions. The package 
provides character translation tables for input and transfer 
and can perform hex to octal to decimal conversions. You 
can place serial input or output buffers directly in any Win¬ 
dows or OS/2 application, for example, to turn a cell in a 
spreadsheet into a serial input or output buffer. The Profes¬ 
sional version also lets you log data directly to a disk file in 
the background while you work with other programs in the 
foreground. 

The Software Wedge vl.1 costs $395 for the Professional 
Windows version, $199 for the Windows version, or $129 for 
DOS. For more information, contact T. A. L. Enterprises, 2022 
Wallace Street, Philadelphia, PA 19130, (800) 722-6004 or 
(215) 763-2620; FAX (215) 763-9711. 


NPPC Aids W4WG Network Development 


Network Program to Program Communications (NPPC) for 
Windows is a tool to help C/C++ programmers create Win¬ 
dows for Workgroups network applications. The library is 
available for either IPX or NetBIOS networks; the API is the 
same for both versions. NPPC for Windows applications are 
also compatible with NPPC for DOS applications. 

NPPC provides high-level functions to perform program- 
to-program communication at the message level. NPPC con¬ 
trols all message queuing, network transmission and 


reception, re-transmission in case of error, initialization, and 
termination of IPX or NetBIOS usage. NPPC for Windows/IPX 
can be used with Novell Netware or any LAN that includes 
an IPX interface. 

NPPC for Windows/IPX and NPPC for Windows/NetBIOS 
each cost $195 or $395 with source. You can purchase both 
libraries for $329 or $729 with source. For more information, 
contact Softwarehouse Corporation, 326 State Street, Los 
Altos, CA 94022, (415) 949-0203; FAX (415) 949-0208. 


AccSys Offers dBASE/Paradox Access for VB 


AccSys for dBASE and AccSys for Paradox are database 
libraries that now support Visual Basic v3.0. The libraries give 
programmers a set of ISAM routines for standard database 
formats, an alternative to the proprietary ISAM routines that 
come with the professional version of Visual Basic. Program¬ 
mers can use AccSys to develop programs that can co-exist 
in networks and Windows DLLs with dBASE, XBASE, and 
Paradox applications. From Visual Basic, you can use AccSys 
to create, read, write, modify, and update Paradox or dBASE 


files. AccSys for Paradox provides control over primary and 
secondary index files as well as tables. AccSys for dBASE 
works with MDX and NDX index files and DBT memo files, 
and also handles the DBF, NDX, and DBT Files in both dBASE III 
(PLUS) and dBASE IV formats. 

AccSys for dBASE and AccSys for Paradox each cost $395, 
or $995 with source. For more information, contact Copia In¬ 
ternational, Ltd., 1342 Avalon Court, Wheaton, IL 60187, 
(708) 682-8898; FAX (708) 665-9841. 


Display and Edit Tree/Network Structures with VAR CHART 


VARCHART v2.2 is a portable library that supplies the 
functions you need to display and interactively edit tree and 
network structures. It is designed to help you easily add 
diagram-editing facilities to the user interface of an applica¬ 
tion such as a CASE or project management tool. The library 
is portable and runs under Windows 3.x, Presentation 
Manager, X-11 (OSF-Motif, OpenWindows, DEC-Windows). Its 
C- compatible interface can be used with many develop¬ 
ment tools, such as Microsoft C/C++, Borland C++ v3.1, Zor- 
tech C++ v3.1, and Visual Basic. 


The new version features a link router to automatically 
route links, and offers automatic or manual positioning of 
nodes, helping the user restructure "spaghetti charts.” In this 
version, nodes can be assigned a variety of attributes, such as 
color, shape, various text fields, fonts, shading, and so on. The 
new version can also process multiple charts simultaneously. 

For more information, contact Netronic Software GMBH, 
PascalStrasse 15, D-5 2076 Aachen, Germany, +49-2408- 
1401; FAX +49-2408-14133. In the US, contact American 
Netronic, Inc., (714) 760-8642. 
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Integrated Scientific Resources Introduces FFTdllfor Windows DSP 


FFTdll is a new Windows DLL from Integrated Scientific 
Resources that includes over 50 functions for computing fast 
Fourier transforms. The library is accessible from any lan¬ 
guage that can call DLLs, and can handle data sets as large 
as available memory. FFTdll is optimized for data sizes that 
are powers of 2,4, or 8. Radix 8 or radix 4 algorithms are sub¬ 
stantially faster than the standard radix 2 FFT. The library 


comes with online help that you can print and that includes 
source code examples you can cut and paste directly from 
the help file. 

FFTdll costs $99 until December 31,1993 and $149 there¬ 
after. For more information, contact the distributor, DH Sys¬ 
tems, Inc., 1940 Cotner Ave., Los Angeles, CA 90025, (800) 
747-4755 or (310) 479-4477; FAX (310) 478-4770. 


Berard Releases OOP Analysis and Design Tool 


The Berard Object and Class Specifier (BOCS) is a graphi¬ 
cal, object-oriented, analysis and design tool. BOCS supports 
the Berard method presented in Edward V. Berard's “Essays 
on Object-Oriented Software Engineering, Vol 1” and also 
complements other methods to fully document individual 
objects. BOCS supports the capture, communication, and con¬ 
sistency-checking of object-oriented analysis and design 
decisions, and allows software engineers to create textual 
and graphical representations of objects and their relation¬ 


ships. Graphical representations include: Petri net graphics, 
semantic networks, state transition diagrams, object-mes¬ 
sage diagrams, and associated templates. 

The Berard Object and Class Specifier costs $595 and re¬ 
quires an 80386 or better running Windows 3.1 or OS/2 2.x. 
For more information, contact Berard Software Engineering, 
Inc., 101 Lakeforest Boulevard, Suite 360, Gaithersburg, 

MD 20877, (301) 417-9884; FAX (301)417-0021; 
info@bse.com. 


Async Professional Now Available for C/C++ 


TurboPower Software has released Async Professional for 
C/C++, a C and C++ version of its Async Professional library for 
Pascal. Async Professional is an interrupt-driven, 
asynchronous communications library. At the hardware ac¬ 
cess level, it supports UARTs, FOSSIL, DigiBoard, and Inti 4. At 
the protocol level, it supports ZMODEM, YMODEM, XMODEM, 
and Kermit. The software can take advantage of the extra 


buffering support of the 16550 UART found in some PCs. 
Modem support includes Hayes, V.32, HST, and MNP Level 5. 

Async Professional for C/C++ costs $189, includes full 
source code, and is royalty-free. For more information, con- 
tart TurboPower Software, P.O. Box 49009, Colorado 
Springs, CO 80949-9009, (800) 333-4160 or (719) 260-9136; 
FAX (719) 260-7151. 


Ml Programmer Offers Visual Windows Programming 


VZ CORP has released vz Programmer v2.2, the latest ver¬ 
sion of their integrated applications development package. 

VZ Programmer provides a visual, interactive environment 
that lets you rapidly create, deliver, and maintain simple or 
complex applications for networked or standalone environ¬ 
ments. 

VZ Programmer lets you graphically construct the applica¬ 
tion user interface and then extend the function of the user 
interface objects. You can create a software component 
library, an extensible set of compound objects that can in¬ 
clude GUI objects or multiple application objects encapsu- 


Pinnacle Updates Graphing Library 

dGE v5.0 is the new version of Pinnacle Publishing’s 
graphics library for DOS. The new version offers four new 
graph types: log-linear X-Y graphs, 3D pie charts, bubble 
graphs, and 3D area graphs. In addition to CGA, EGA, and VGA 
support, dGE now provides 256-color support up to 1024x768 
resolutions for VESA-compatible SVGA cards. The package 
has been recoded to use less memory and now offers 
proportional fonts, bitmaps, and icons. dGE 5.0 also provides 


lated in a single component, providing a higher level of 
reusability than function or class libraries. The package 
provides cross-platform support between Windows 3.1 and 
OS/2 PM, and comes with 20 predefined object classes and 
over 60 system, menu, and graphical functions. DDE support 
is also built-in. 

VZ Programmer v2.2 costs $595 for Windows 3.1 or OS/2 
PM. For more information, contact VZ Corp., 175 South Main 
Street, Suite 1550, P.O. Box 3683, Salt Lake City, UT 841 ID- 
3683, (801) 595-1352; FAX (801) 328-4404. 


a low-level API accessible from C or assembly language. 
Another new feature is compatibility with the company's 
graphics server for Windows, allowing programmers to move 
dGE programs to Windows with little or no change. 

dGE v5.0 costs $299; upgrades cost $99. For more infor¬ 
mation, contact Pinnacle Publishing, Inc., 18000 72nd Ave. 
S., Suite 217, Kent, WA 98032, (800) 788-1900 or (206) 251- 
1900; FAX (206) 251-5057. 


DEPGEN Automates Makefile Generation 

Sector Seven has released the Dependency List Gener¬ 
ator (DEPGEN) v2.0, a program that reads C source code and 
include files to create a makefile and dependency list New 
features include support for multiple directory projects, cross- 
compilers and linkers, libraries, and DLLs. DEPGEN requires 


DOS v3.3 or better and supports ANSI C, Borland's make and 
Microsoft’s nmake. 

DEPGEN v2.0 costs $65. For more information, contact Sec¬ 
tor Seven, P.O. Box 11391, Burke, VA 22009, (703) 866- 
9477. 
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00 Database Available for Windows NT 

Objectivity/DB Starter Kit for Windows NT is a new 
product to bring the object-oriented database management 
of Objectivity/DB to Windows NT. Object databases do not re¬ 
quire you to decompose data to records or tables; they can 
model large amounts of complex data that vary dynamically 
and have arbitrary data relationships. The starter kit will be 
followed by full connectivity to provide transparent access, 


storing, and sharing of objects distributed in multiple 
databases and mixed networks of UNIX, VMS, and Windows 
NT platforms that use NFS. 

The Objectivity/DB Starter Kit for Windows NT costs 
$2,995. For more information, contact Objectivity Inc., 800 El 
Camino Real, Menlo Park, CA 94025, (415) 688-8000; FAX 
(415) 325-0939; info@objy.com. 


SQA TeamTest Automates GUI Testing 

SQA TeamTest is a new automated GUI testing system 
for Windows. The product integrates automated GUI testing 
with team workflow tracking and reporting, and is built on 
SQA's Team Testing Architecture, based on a network test 
repository. The test repository coordinates the work of any 
number of testers on a network. As testers use SQA Team- 
Test from their PCs, the test repository is automatically up¬ 
dated during all stages of the testing process: test planning, 
test development, unattended test execution, test results 
analysis, and incident/problem tracking. 

SQA TeamTest uses Visual Basic to provide an extensible 
test script language. The product lets you rapidly create 


tests by recording the testers' actions at the Windows object 
layer and generating test scripts using SQA’s GUI object ex¬ 
tensions to Visual Basic. SQA TeamTest can manage a large 
volume of test results, offering test cycle tracking and report¬ 
ing. All failed tests are tracked along a customizable inci¬ 
dent/problem/resolution workflow cycle. A variety of reports 
are available to measure the progress of the testing effort 
and document the “test asset” inventory. 

SQA TeamTest costs $1495 per license. For more informa¬ 
tion, contact Software Quality Automation, Inc., 10 State 
Street, Woburn, MA 01801, (617) 932-0110; FAX (617) 932- 
3280. 


WexTech Ships International Version of Doc-To-Help 


WexTech has released an international version of its Doc- 
to-Help, a Word for Windows add-on that makes it easy to 
create WinHelp files. Doc-to-Flelp vl.la supports all interna¬ 
tional language versions of Word for Windows. The new ver¬ 
sion includes support for Windows 3.1 help macros, easy 
importing of existing . rtf files, customizable help project 
files, interactive control of help window size and colors (both 


scrolling region and non-scrolling region), and support for 
Microsoft's segmented hypergraphics editor (shed. exe). 

Doc-To-Flelp vl.la costs $295; the international version 
costs $375. Registered users can upgrade for $15. For more 
information, contact WexTech Systems, Inc., 310 Madison 
Ave., Suite 905, New York, NY 10017, (212) 949-9595; FAX 
(212)949-4007. 


DRTS Tackles Distributed Revision Control 

The Distributed Revision Tracking System (DRTS) from ILSI 
is a suite of code management tools designed to simplify 
software version, revision control, and release integration. 

DRTS automatically tracks changes made at different 
development sites, addressing the needs of teams perform¬ 
ing distributed developments. Project files can be shared 
across disparate hardware and operating system platforms; 
currently the tools run on DOS, SCO UNIX, and SunOS plat¬ 


forms. The package also supports the ability to develop and 
maintain multiple concurrent software releases, allowing 
changes from one release to be easily propagated into 
another. 

DRTS vl.O costs $300 for a single-user DOS license, or 
$500 for a single-user UNIX license. For more information, 
contact ILSI, 6325 East Monte Cristo Avenue, Scottsdale, 
AZ 85254, (602) 991-8281. 


APL*PLUS II Gets Windows GUI Toolkit 

Manugistics has released APL'PLUS II, an APL develop¬ 
ment tool that lets developers build Windows applications 
with an array-programming language. This version features a 
new object-oriented Windows GUI Toolkit that improves the 
visual programming capabilities of the product. The screen 
design tool offers a toolbar and alignment grid that lets 
programmers create screens by dragging and dropping 
visual images of Windows controls. Pressing one button on 
the editor creates the callback routine that runs when the 
user interacts with the control. After you design a screen, a 
new utility program automatically generates the APL code 
needed to implement the desired user interface. 


The new version also adds new object classes that sup¬ 
port Windows graphics and printing. The new graphics opera¬ 
tions include bigmaps, icons, line segments, filled polygons, 
circles, arcs, and text display. The package includes a new 
Toolbar class object and a library that gives a sculptured 
three-dimensional appearance to Window controls. 

APL'PLUS II costs $1700. The version 5.1 update is free to 
current users enrolled in Manugistics’ HelpLine Plus Support 
Program. For more information, contact Manugistics at (800) 
592-0050 or (301) 984-5123. 
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Readers' Forum 


Ron, 

I found your Practical C++ article both intuitive and per¬ 
suasive. As a professional software developer I have (of 
course) run across the problems that you described. My per¬ 
sonal solution tended to take the split functions approach in 
general and checking a variable approach in a few. 

The only thing that was still bothering me when I finished 
reading the article was: how come this is the first time that I 
have heard or seen that approach? It seems (after reading 
your article) like an elegant and effective solution to a well 
known problem. 

If you aren't getting NT Developer you might want to look into 
it Richard Shaw and Bruce Eckel are doing a thread on how to 
write a multi-threaded class. Keep up the good work! 

Scott Love 
CompuServe: 73700,732 


I couldn’t actually recall seeing precisely that approach 
discussed in print. On the other hand, about a week after I 
finished that column, a BIX user asked how to deal with 
constructors that can fail and someone immediately rattled 
off all the approaches listed in my column. With C++, much 
more so than C, I think it pays off to be plugged in to the 
C++ programming community. One good place is BIX, with 
folks like Bjarne Stroustrup and Greg Comeau actively par¬ 
ticipating. Another is the C+ + news groups on the Internet. 
There’s just a wealth of collective experience that is only 
beginning to appear in books. I hope my column can pro¬ 
vide a conduit to help distribute some of that information. 

I have to admit that I haven’t been able cough up the 
more than $100 it costs to subscribe to NT Developer. / 
think it’s a mental block about triple-digit prices, as I also 
have not been able to make myself purchase Microsoft's 
MSDN CD-ROM. If I’m ever going to pay that much for a 
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subscription, the money will have to go first to Software 
Practice & Experience, my all-time favorite journal, which I 
currently have to drive to the local university to read. Maybe 
I can borrow a copy to peruse the article you mentioned — 
it sounds interesting, -rib 


To: ronb@rdpub.com 

Re: Constructors that can fail 

Great article! Very helpful! I am starting my first big C++ 
venture and your article squarely met my needs. 

C++ books do have code in them that is simple but 
dangerous. For example, they define a string class String and 
then do operations like string concatenation String c = a + b 
without ever checking if there was memory to construct c. I 
fear that, influenced by such books, a whole new generation 
of programmers will forget to check for out-of-memory errors. 
Also, how do you deal with class libraries that don't give you 
a way of checking if their Strings really exist or if the data 
inserted into a doubly-linked list has found an existent home? 


By the way, Watcom C++ version 9.5 for 386 class 
machines says it supports exceptions, but I haven't tried using 
them yet so I can’t tell you if it works. 

Jonathan S. Levinson 
jsl@world.std.com 

As you point out, creating really reusable C++ classes is 
not trivial, and memory management is one of the significant 
problems. I became much happier with C + + when I 
stopped focusing on creating very general classes and 
started focusing on just creating the best solution I can for 
the problem at hand. If I haven’t created custom code to 
solve a particular kind of problem three or four times, I 
probably don't know enough to create a reusable class for 
that problem anyway. 

I would sure like to play with exceptions; maybe I'll have 
to clear off enough disk space for yet another compiler. I 
like my code to work with the major compilers, so that slows 
me down a little on using new features. If Microsoft doesn't 
get templates implemented soon, though, I'm going to have 



Developer's 

Marketplace 


ITL 

HARDWARE 
INTERFACE LIBRARY 
FOR THE IBM PC 

Write device drivers in less time. 
Focus on your hardware, not IBM's. 
Use high level C or assembly. 

Over 80 functions for: 

- Controlling DMA Hardware 

- Hardware Interrupt Control 

- Access to Virtual DMA Services 

- DPMI Host Access 

Introductory price: $95 through 9/30/93. 

Includes Interfaces for Assembly and 
Borland/Turbo C++ 

For more information, write or call: 

Intelligent Tools Company 

T— I- -L 817-725-7455 

IN I n rl I PO BOX 6334 

-U— ILJ LJ L_ Abilene, TX 79608 

□ Request 170 on Reader Service Card □ 




DOS 


Wth 


5 Portable Software, Inc 


g? 1 800 484 2045 ex 3000 


404-952-2432 
FAX 404-955-1375 


□ Request 199 on Reader Service Card □ 


SmartHcap is an ANSI portable malloc 
and new for DOS, Windows, NT, OS/2, 
UNIX and other platforms. Proprietary 
algorithms deliver speed improvements 
up to 100X versus other commercial 
mallocs, especially for large heaps in the 
presence of virtual memory. SmartHeap 
localizes data structures in their own 
heaps. Plus it includes numerous fixed- 
size and handle-based APIs. Debugging 
facilities isolate leakage, overwrites, 
double-freeing, wild pointers, and many 
other errors to responsible file/line/pass 
count. Exceptionally reliable - used by 
a "who’s who" of commercial software 
publishers. No royalties. Source avail¬ 
able. 

CALL FOR FREE 

WHITE PAPER, BENCHMARKS, 
AND ERROR REPORTS 


Software Publishing. Inc. 

800-441-7822 / 206-525-8218 
FAX 206-525-8309 

CompuServe: 70751,2443 
Internet: devtools@microquill.win.net 




Create High 
Performance 
Network 
Applications 
FAST! 

Now Shipping 
Version 2.03! 

60 Day Money 
Back Guarantee. 1 


0 Shared DLL resources 
supports multiple applications 
and instances. 

0 Full post processing support 
& notification via messages 
(wait, no-wait, and polled). 

0 Complete NCB and attached 
data buffer functions simplify 
memory management. 

0 Complete documentation and 
on-line API help reference. 

0 Control panel utility allows 
dynamic DLL configuration. 

0 WINDOWS.TXT compatibilty 
for DOS support. 

0 No royalties, full source with 
demos. Now only $129.00! 


SIGMA SOFTWARE RESEARCH 

702 Windridge Dr., Atlanta, GA 30350 

m TEL/FAX (404) 992-0536 

Also available at the Programmer's Connection! 


□ Request 133 on Reader Service Card □ 


Page 84 — Wirtdows/DOS Developer's Journal 


Network Toolkit 


This kit provides an abstract programming layer 
for developing network applications that are 
independent of the underlying network protocol. 
Developers write one application that will run 
over NetBIOS, IPX or Windows Sockets 
transparently without having to master the API 
set for each of the protocols. All network services 
are event-driven with both connection-oriented 
and connectionless circuits supported. US$495. 


Interfaces: 

Visual Basic™ custom control (VBX) 
Microsoft® or Borland® C/C++ 
Borland Pascal 



Intelec Systems 

10201 W. Markham, Ste. 101 
Little Rock, Arkansas 72205 
Fax 501.221.7412 
501.221.3600 


□ Request 188 on Reader Service Card □ 

September 1993 


















































Open your 
with Desi 
P Icons & 
ft for Devel 



Font 




Over 4000 high-quality, custom-designed icons, 
buttons and controls ready to add character, color 
and sophistication to any Windows application. 

With DesignClips royalty-free icons for 
developers, in an extended palette of 120 
colors, grays and in b&w, you can easily: 
Personalize your Windows product with 
unique icons available only from LetterSpace 
Modify and customize DesignClips Icons 

Save time, labor and resources over creating 
your own icons and buttons. 

Set your product apart from the competition 
Save money with low-price high quality icons 

DesignClips Icons— Designed to change 
your business into an industry. 

LetterSpace 

338 E 53 St #2C NewYork NY 10022 Or call (212) 935-8130 


□ Request 150 on Reader Service Card □ 


Phone Sound: Simple! 


For Windows/DOS Voice Mail & Fax Developers 



Professional 
Tools for 
your Voice 
Mail, Fax & 
Audiotex 
Applications 


1. Create fantastic prompts Multimedia Wave (16, 8 & 

and save time with MS ADPCM), linear 16 & 

VFEdit®\ Record, crop, cut, unsigned 8, plus Dialogic 4 
copy, paste, mix, fade, echo, & 8 at any sample rate! 
volume & more with your 4. Scrib e Transcription 
Dialogic™ D4x/12x boards, y f or DOS plays digital 

2. Add Voice Mail power to audio files in the background 

your MS Windows apps with without voice mail hardware! 
TI/F DLL ™, our Tel I/F 5. Add Text-to-Speech 
Dynamic Link Library. capability to your apps with 

3. Audio ToolBox™ VoxFonts ™, our "software 

converts to and from _ only" text-to-speech library! 


Order Now: 1-800-234-VISI 


I Voice Information Systems: 24 N Merion Ave, Bryn Mawr, Pa 19010 I 

Tel: 215-747-5035/ BBS: 215-747-5062/ Fax: l-800-234-FXIT l 


□ Request 192 on Reader Service Card □ 


SDLC, BSC, HDLC, 
X.25 ON THE PC 

Use the Sangoma SDLA card to 
provide link support for your product 
that is cost effective, full featured, rock 
solid and easy to use. 

• Line speed to 180kbps 

• Operating statistics and built in 
datascope make your product easy 
to configure and debug 

• Menu driven test program included 

• Primary and secondary SDLC with 
multiple addresses 

• HDLC LAPB, LAPD, NRM mode 

• CCITT 1988 X.25 implrementation 

• High level interfaces under DOS, 
Unix, Windows, OS/2 

SANGOMA Technologies Inc. 

Tel: (416) 474-1990; (800) 388-2475 
FAX: (416) 474-9223 


Does your company provide 
tools, products, or services 
for advanced Windows 
programmers? 

Then reach over 27,000 
serious programmers in: 

Windows/DOS 

□ DEVELOPER’S JOURNAL 

Call 913-841-1631 today for 
information about advertising 
opportunities in Windows/DOS 
Developer’s Journal. 

Advanced. Serious. 
Technical. 

Brian Osborn - Continental Europe. 

Ed • East Donna - Midwest Edwin - West 


VB/ISAM™ 

CB/ISAM™ 


FAST, CLEAN, AND EASY 
serious data management 
for Visual Basic ™ and C, 
both Windows"" and DOS. 

For professional applications since 8/91: 
VARIABLE-LENGTH fields and multi-format 
records to 64K, SUPER-FAST and reliable 
with files to 512 MB. Automatically 
maintains up to 80 indexes: small, friendly 
API, 50KB DLL. Special offer: multi-user 
$169.95, single-user $99.95. No royalties. 

^q£hvareJiource 

42808 Christy Street, Ste. 222 
Fremont, California 94538 
Tel. (510) 623-7854 ■ Fax (510) 651-6039 



Use all 
of your 
senses! 

add multimedia to your 
Windows projects 
The Sound Clip Collection 


WW2 

Bagpipes 

Animals 

Voyager 

LA Riot 

Subway 

Indians 

Drains 

Spacemen 

Kids 

Cars 

...and much, 

Volcano 

Quakes 

much more 


PC speaker driver included! 

Only $34.95 NEW ART INC. 

(NYS residents 200 W. 79 Street 

add tax, Windows suite 8H 
3 .1 required) NYC, NY 10024 

_ Ws have_Phqtq_Cjip artJoo!_ _ 
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CD 


EACH TOPIC 
DISK 

CONTAINS 

HUNDREDS OF 
APPUCATIONS 

THOUSANDS 
OF FILES 

MANY WITH 
FULL SOURCE 
CODE. 


KNOWLEDGE MEDIA 

RESOURCE LIBRARY 


ROMs 

i§81IS13&w 

GRAPHICS 

ANIMATION, PAINT. CONVERTERS. 
FRACTAL, DRAWIN& JPEG. 

MAPPING, G4F. PLOTTING PAINT. 

AUDIO 

CONVERTERS, MKX, EDITORS. 

MIXERS. WOOS MUSfC, PLAYERS, 

snd, speech Packers, voc, wav 


MULTIMEDIA 

authoring svstsms, presentation 

PIAVBS, CONUNT MEDIA UBRARIES 


ORDER DESK: (800) 78 CD ROM 
ORDERS BY FAX (916) 872-3826 
VISA and MASTER CARD or COD 
436-B Nunneley, Paradise, CA 95969 
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C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, cross-ref, file/function index. 

• C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METRIC ($59) Counts path complexity, 
counts comments, code, 'C' statements. 

• C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

• SPECIAL: C-DOC ($199) All 5prqgrams 
integrated as DOS program (<15,000 lines) 

• NEW! C-DOC Professional ($299) 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deferred reports. 

• 30-DAY Money-back guarantee CALL NOW 


SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Mississauga 

ONT, Canada Voice/Fax (416)-85fi 

1-44661 

L5N-4M1 Demos/BBS (416)-85S 


see AD INDEX for our larger ad 
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eXAfniHATOR 


Simulation of the Microsoft? Windows™ Certified Professional Examinations 


Enhance your value to clients, peers and employers 
using Examinator, an interactive Windows 3.1 pro¬ 
gram that helps you prepare for and pass the Micro¬ 
soft Windows certification exams given at authorized 
testing centers worldwide. 

• Four complete simulated exams 

• Exam registration instructions and study outlines 

Benefits of this credential include a license to use 
the Microsoft Windows logo, a wall certificate, 
membership card, MCP directory listing and more! 
®89 + ®4 s&h To order, call (615) 327-1858 
VISA/MC/Check/MO/COD fax (615) 320-6594 



Transcender' 

Dept. D Corporation 

242 Louise Ave. 

Nashville, TN 372Q3 
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to drop them from my compatibility list — templates are too 
useful to pass up much longer. Thanks for the letter! -rib 


Ron: 

There you've gone and done it again! Back in May, when I 
had to write a device driver, there was T. W. Nelson's super 
self-loading device driver article and code to help me out. Best 
example of DOS device driver writing I’ve seen, and that in¬ 
cludes Robert Lai's book about device drivers, which is decent. 
Now I have to write some Windows code to communicate 
between a Windows program and a TSR via the DOS multi¬ 
plexer interrupt, and here we have Charles Mirho’s fine DPMI 
article and sample code. Wow! 

Do you read my mind, or what? This is great. The number 
of hours I've saved from reading just the device driver article 
alone and slicing and dicing some of the assembly code pays 
for 10 subscriptions to Windows/DOS Developer's Journal. 


This does wonders for shortening product development 
cycles. Today, we just shipped our device driver as part of our 
latest product release, and it is rock solid. Keep it up! 

Best regards from a veteran programmer not too old to 
learn new tricks, 

Ben Myers 
Spirit of Performance, Inc. 

Harvard, MA 

The model that Robert Ward conceived of for this 
magazine was that of a forum for programmers, so it's a big 
pat on the back to hear from a programmer who is making 
immediate hands-on use of the articles and code supplied 
by other programmers. We have another interesting article 
from Tom Nelson coming up in the near future, by the way. 
Thanks for the compliment, and thanks to Charles and Tom 
for all the hard work they did on their articles, -rib 



Developer's 

Marketplace 


SVInstal 


Version 2.0 


Installs anything... 

You just run the install builder, telling it your 
company name, application name, default 
directory, disk space required and list of files. 

No programming or scripts to write. 

What SVInstal does... 

♦ Creates destination directories, copies files. 

♦ Makes program group, puts in your icons. 

Features ... 

Progress gauges, multiple source disks, directory 
trees, file compression, network server/client or 
standalone. No royalties! 

Soft Ventures (dept, wdj) c A fir 
Box 22183 Bankers Hall 

Calgary Alberta Canada (plus $5.00 s&h) 

T2P4J5 (403)278-1681 Canadian $69.95 + 7% GST 
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Tools for Novell’s Btrieve® 


Bsupport III Bsupport II 

Bed it 3.0 - Btrieve file viewer/editor. 
Banalyze 2.0 - Btrieve app. debugger. 

Brun 2.2 - HI I II replacement plus source. 
Bereate 2.0 - file creation utility. 

Bcheck 2.0 - Btrieve file analyzer. 

Xsupport 1.0 - build data dictionary 
(.DDF) for Access, OV, 
Crystal Rpts. 

Xport 2.0 - export/import CDF, SDF, 
dBASE. 

Call for information on additional 
products and FREE demo! 

Information Architects, Inc. pj i; (goo) 359-2721 
3130 Pine Tree Road ( 517 ) 887-8000 

Lansing, MI 48911 Fax:(517) 887-2366 
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HDTI ikiLf relief from 
Ur I Limrv linker headaches 


OPTLINK for Windows offers 
Borland-based developers with 
33% faster linking, 33% smaller 
programs, and fully supports 
Turbo Debuger. Links Visual C++ 
programs 50% faster too! 

SLR Systems, Inc. 

(412) 282-0864 • Fax: (412) 282-7965 
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1:03 

TUB"' is FASTEST! 


0:41 


• •S'si 0 \ 9 . 0:09 

SMk iSWtSSI ...jTihr, , 

RCS™ 4.2 

PVCS™ TLIB™ 3.0 TLIB™ 5.0 


Times are to update a 45K library on a PC/XT. PVCS and TLIB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TLIB 5.0 are newer. 


TLIB™ is BEST! 

"Do not be fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TLIB has features and power to spare” 
John Rex, Computer Language 
“TUB is a great system" J. Vallino, PC Tech J 

• Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching. 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc.. Integrates with Opus’" MAKE & Slick " MAKE. 

MS-DOS $139, OS/2 $195 + shipping visa/MC 
5 station LAN license $419 (OS/2 $595), call for other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919)233-8128 

□ Request 137 on Reader Service Card □ 



We Understand The 
Programmer's Mind 


When the country's top firms look for the 
best developers available, they turn to 
Bateman. Why? Because we specialize in 
Microsoft Windows, NT, OS/2 and Macin¬ 
tosh recruiting nationwide. So if it's time for 
a career move, give us a call. We under¬ 
stand your skills, and the marketplace for 
them... we understand you. 

0 Bateman Inc. 

5847A Uplander Way 
Culver City, CA 90230 
Tel: 310-641-4100 Fax: 310-641-2900 
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GCP++ is the 
development 
solution for 
TCP/IP under 
Windows! 

Encapsulates TCP, UDP, TELNET & TFTP in a 
robust and easy-to-use server, so you start 
with proven socket library code! 

Genisys Comm Pack++ 

• OLTP, emulators, DBMS, all client/server apps • 
• VB Custom Control and DLL interfaces • 

• Low-cost stack option for integrators • 


GENISYS Comm, Inc. 


Download the GCP++ Evaluation Kit today!; 



moosoft* 

WINDOWS* 

COMfKtmF. 


GENISYS Comm, Inc. 
314 S Jay St, Rome, NY 13440 
315-339-5502 • tax 5528 
GCP++@GENISYS.com 
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SpyWorks-VB 

For Visual Basic™ - Windows 

SpyWorks-VB allows you to do virtually 
anything in Visual Basic that is possible 
using other languages such as C. It 
includes controls that easily subclass 
VB forms and controls, detect keyboard 
events, and support callback functions. 
SpyWorks includes debugging tools to 
view message and event history, detect 
API parameter errors, Browse Windows 
memory and resources, and retrieve 
information about any window, form or 
control in the system. 

SpyWorks-VB is only $129 + $5 s&h ($15 
outside U.S & Canada). Visa/MC orders 
include phone and exp. date. CA residents 
add 8.25% sales tax. Dual media - Requires 
VB2.0 

Desaw are 

5 Town & Country Village #790 

San Jose, CA 951 28 

(408) 377-4770 fax:(408) 371-3530 
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Career Marketing Associates 

7100 East Belleview Avenue, Suite 102 
Englewood, CO 80111 

Today, 1993 

Dear MS WINDOWS DEVELOPER: 

You’re talented. You know your 
C++ and API calls and all the 
alphabet buzzwords. But does your 
boss understand and appreciate you? 
I don’t think so. He thinks OLE Is 
bullfighter talk. 

So teach them a lesson and take 
your services elsewhere. Maybe you 
should contact a professional 
recruiter. I would suggest Career 
Marketing Associates In Colorado. 
Why? With 280 affiliates all over the 
country, we might come across the 
perfect opportunity for you. So write, 
fax, call, or communicate in your 
dreams with us. We want to hear 
from you. > 


Sincerely, 



Gary Patton 
303-779-8890 
FAX 303-779-8139 


f ; a 

Windows 

Developer Jobs 

Specialists in jobs for software 
engineers in leading edge technology. 
Windows, PM, GUI, Languages, AI, 

Mac, CASE, Video, Realtime. 

Nationwide contacts with both large 
and small companies including equity 
startups. Many of our clients develop 
and publish commercial software 
products. Managed by graduate 
engineers. Never a fee to an 
applicant. 

1 - 800 - 231-5920 
Scientific Placement, Inc. 

SPI-8, Box 19949, Houston, TX 77224 (713) 496-6100 
SPI-8, Box 71, San Ramon, CA 94583 (510) 733-6168 
SPI-8, Box 4270, Johnson City, TN 37602 (615) 926-6188 
Fax: 713-496-6802 please use Fine Setting on Fax 
Email: Ascii preferred: Internet LSH@Scientific.com; 
Vcompuserve: 71250,3001; Genie: D.SMALL6 J 
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CQMV. - COM4: WITH WINDOWSI 

1,270R 4 PORT RS-232 BOARDS 
RS-232 AND RS-422 VERSIONS 
XT AND AT INTERRUPT JUMPERS 
OTHER PRODUCTS INCLUDING LAPTOP 
ADD-ONS 

DELIVERY FROM STOCK. 

MADE IN USA 

EXCELLENT TECHNICAL SUPPORT 


SEALEVEL SYSTEMS INC. 
PO30X630 

LIBERTY, SC 29657 e 

803-643-4343 


,SEALEVEL 


□ Request 115 on Reader Service Card □ 


Opt-Tech Sort/Merge 


New -Version 5 

High performance Sort/Merge/Select 
utility. Run as a stand alone 
utility or CALL as a subroutine. 

Supports most languages and 
filetypes including Btrieve 
and dBase. Unlimited filesizes 
multiple keys and much more. 

MS-DOS, Windows $149 
OS/2, UNIX $249 

Call to order or for free info. 


Opt-Tech Data Processing 
P.O. Box 678 
Zephyr Cove, NV 89448 

. (702) 588-3737 > 
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CDROMs for Work and Play! 


Giga Games CDROM $39.95* 

Over 2700 Games for Microsoft Windows and 
MSDOS. 250 Megs of games plus 150 Megs of 
source. Lots of educational games. July 1993. 
CICA MS Windows CDROM $24.95* 
2518 files of MS Windows programs. Utilities, 
games, source code, programming tools, fonts, 
drivers, icons. April 1993. 

Simtel MSDOS CDROM $24.95* 

650 Megabytes, 9000+files.Programming tools, 
utilities, editors, education, source 
code and more. May 1993. 

* Shareware programs 
require separate payment 
to authors if found useful. 

1-800-786-9907 orders@cdrom.com 
FAX 1-510-674-0821 

$5 S&H per order (USA Canada Mexico) 

$10 overseas 1-510-674-0783 AMEX/VISA/MC/COD 
'**. All our disks are 
,.** unconditionally guaranteed. 

Walnut Creek CDROM 

4041 Pike Lane, Suite D-699 
Concord, CA 94520 
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Macro 
Language 
"To Go" 


Easily add Netlogic’s full featured 
macro language facility to your 
Windows application — at a fraction of 
the time and cost of developing it your¬ 
self. Seamless integration. Full basic 
syntax. Integrated editor and debug¬ 
ger. Extendable and modifiable. For 
more information: Netlogic Inc., 915 
Broadway, New York, NY 10010. 
Phone 800-638-0048. Fax 212-533-9524 

ProMacro ™ 

Your Application’s Shortcut to Power 

□ Request 171 on Reader Service Card □ 


2 tm 

. 

The Art of Visual Basic Programming ™ 

This amazing new book by J. D. Evans, Jr. unlocks 
the secrets of Windows and Visual Basic 
application design and programming. It explains 
Windows design from a unique and easy to 
understand perspective. Smart Objects, Hybrid 
Objects, Control Coupling, Events, Focus, Event 
Triggering, Visibility, Form and Module Code 
Placement, DLL Parameter Passing, Variable 
Scope, Strings, and Structures are described and 
explained. Enlightening allegories and annecdotes 
make this one of the most unusual and informative 
Windows books ever written. This book is the 
Rosetta stone for Windows and Visual Basic! 


Book: $29.95 Companion Disk: $9.95 


ETN Corporation 

RD4 Box 659 Montoursville, PA 17754-9433 
(717) 435-2202 (Sales) (717) 435-2802 (FAX) 
AMEX/MC/VISA/Check/MO/PO/COD 
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CUSTOMIZE YOUR 
WINDOWS! 

For Experienced Programmers- 

GIVE WINDOWS YOUR OWN 
DISTINCTIVE LOOK. 


Custom Static Styles 


OK 


Cancel 


Custom Static Types 
Bitmap 

Bitmap Stretch 
Bitmap Win. 
Frame 
Line Horz. 

Line Vert. 


Icon 

Icon Window 
Rectangli 
Text 

Text Low< 
Text Rais 
Text Shat 


Help 


Horizontal Alignment 

Left Center E 


Vertical Alignment 

Top Center 


* ' .... 

3D Appearance 
Border 

Lowered E 

Text Styles 


Expand Tabs 

Mo Prefix 

Left No W.W. 

jingle Lir 

Basic Styles 


Visible 

Group 

Disabled 

Tab Stop 


WILLIAM SMITH 


ROBERT WARD 


Extend the Windows API with your 
own components 

Build replacements for standard 
controls 

Create controls that handle huge 
amounts of text 

Learn how to 

• create a toolbox class 

• create a custom dialog class 

• interface custom controls to 
the Dialog editor 




CUSTOM 


CONTROLS 


WINDOWS 
CUSTOM 
CONTROLS 


William Smith 
Robert Ward 


This book includes all the code for a 
powerful set of ready-to-use custom 
controls. You can modify the code for 
your own design. 


Compiles under Microsoft C/C++, Quick 
C, and Borland C++ and has been 
tested under Windows 3.1 



Companion Disk for $29.95 

ORDER TODAY! 

Order: Book W99, Disk W99d, 
Book and Disk W99c 



RD 

913-841-1631 

VISA 

Technical 

FAX 913-841-2624 



□ Request 338 on Reader Service Card □ 







































































































ANOTHER DEBUGGING BREAKTHROUGH 


BOUNDS-CHECKER FOR WINDOWS! 



NEW! BOUNDS-CHECKER for Windows is the only totally automatic 
solution to your Windows memory corruption, heap corruption and resource 
leakage problems. 

BOUNDS-CHECKER for Windows is an easy to use utility that automatically 
detects problems in your local heap, global heap, stack or data segment. It also 
tracks resource allocation / de-allocation, performs full parameter checking 
(even when not using the debug kernel) and handles all Windows faults. In one 
step, you can quickly and easily flush out some of the most aggravating bugs that 
a Windows programmer is likely to encounter. 

Using BOUNDS-CHECKER for Windows is simple, there are no changes 
to be made to your source in any way, and no linking of code or macros into 
your executable. When a bug is found, BOUNDS-CHECKER for Windows 
pops up showing you the source code that caused the problem. 


BOUNDS-CHECKER for Windows 
quickly & easily traps: 

• Memory and heap related corruption problems 

• Library routine over-runs of strings, 
arrays and structures 

• Attempting to free bad blocks 

• NULL pointers the instant they are referenced 

• Resources that were not freed 

(shows your actual source line that created the resource) 

• Errant parameters passed to API routines 

• Processor Faults 

Order NOW! Only $199 


For even more debugging power at a great value you can order BOUNDS-CHECKER for Windows in one of our package 
bundles that include other Nu-Mega debugging tools: 

BOUNDS-CHECKER for DOS & BOUNDS-CHECKER for Windows $298 

BOUNDS-CHECKER & Soft-ICE (DOS or Windows versions) $499 

Get all 4 products (BOUNDS-CHECKER & Soft-ICE for DOS & Windows) $770 — SAVE $400! 


We're making C/C ++ a Safe Language! 


Call (603) 889-2386 
fax (603) 889-1135 

| 

fr N 

u-Mesa 

RISK = NULL 

30 DAY 

MONEY-BACK GUARANTEE 

P.O. Box 7780 

Nashua, NH 03060-7780 U.S.A. 

'TECHNOLOGIES INC 

24 HOUR BBS 
603-595-0386 


BOUNDS-CHECKER FOR WINDOWS, SOFT-ICE, AND NU-MEGA TECHNOLOGIES are trademarks owned by Nu-Mega Technologies, Inc. All other trademarks are owned by their respective owners. 
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